Notion

Sync data to Notion databases as pages. Zeotap creates or updates pages in a Notion database, mapping each row of data to page properties. Use this to maintain a live knowledge base, project tracker, or CRM table powered by your warehouse data.

Prerequisites

A Notion workspace
A Notion internal integration with access to the target database
The database must be shared with the integration (via the Share menu on the database page)

Authentication

Integration Token

Go to My Integrations in Notion
Click New integration
Name the integration (e.g., “Zeotap Sync”) and select the workspace
Under Capabilities, ensure Read content, Update content, and Insert content are enabled
Click Submit and copy the Internal Integration Secret (starts with ntn_)
In Zeotap, paste the token into the Integration Token field

After creating the integration, you must grant it access to the database:

Open the target Notion database page
Click Share in the top-right corner
Search for your integration name and click Invite
The integration now has access to read and write pages in that database

Configuration

Notion does not require additional configuration fields beyond authentication.

Target Settings

Field	Type	Required	Description
Database ID	Text	Yes	The ID of the Notion database to sync pages to. Found in the database URL: `https://www.notion.so/{workspace}/{database_id}?v=...`. Copy the 32-character hex string before the `?`

Supported Operations

Sync Modes

Mode	Supported	Description
Insert	Yes	Creates new pages in the database for each row
Update	Yes	Updates existing pages (requires `page_id` field in mapping)
Upsert	Yes	Creates pages if no `page_id` is present, updates if `page_id` is provided
Mirror	—	Not supported

Audience Sync Modes

Notion does not support audience sync modes. Notion databases do not have a list membership concept, so audience operations (add, remove, mirror) are not applicable.

Features

Field Mapping: Yes — map source fields to Notion database properties
Schema Introspection: Yes — Zeotap reads the database schema to show available properties and their types

Required Mapping Fields

Field	Description
Title	The title property of the Notion page. Every Notion database has exactly one title column that serves as the page name

Default Destination Fields

Field	Type
Title	title

How It Works

Zeotap syncs data to Notion one page per row:

On connection, Zeotap reads the database schema to learn each property’s type (title, rich_text, number, select, etc.)
For each row in the batch, Zeotap constructs a typed property payload matching the database schema
In insert mode, a new page is created via POST /v1/pages
In update mode, an existing page is updated via PATCH /v1/pages/{page_id}
In upsert mode, rows with a page_id are updated; rows without one are created as new pages

Property Type Mapping

Zeotap automatically maps values to the correct Notion property format:

Notion Type	How Values Are Mapped
title	Text content
rich_text	Text content
number	Numeric values (integers and decimals)
checkbox	Boolean values (`true`/`false`, `1`/`0`, `yes`/`no`)
select	Single option by name
multi_select	Comma-separated option names
date	ISO 8601 date string (e.g., `2024-01-15`)
url	URL string
email	Email address string
phone_number	Phone number string

Batch Behavior

Notion’s API does not offer a bulk create/update endpoint. Each page is created or updated individually. Zeotap handles rate limiting automatically with retry and exponential backoff.

Rate Limits

Notion enforces an average rate limit of 3 requests per second (2,700 requests per 15-minute window) per integration token. Zeotap respects Retry-After headers and uses exponential backoff when rate limited.

For large syncs, expect approximately 3 pages written per second. A sync of 1,000 rows takes roughly 5-6 minutes.

Best Practices

Use meaningful titles: The title property is required and serves as the page name in Notion. Map it to a descriptive field like a name, email, or identifier
Prefer upsert mode: If re-syncing data, use upsert with a page_id mapping to avoid creating duplicate pages
Limit property count: Only map fields you need. Each additional property increases the payload size and processing time
Use select for categorical data: Map categorical fields (status, region, tier) to Notion select properties for filtering and grouping in Notion views

Troubleshooting

The integration must be created in the same workspace as the database. Verify the integration is listed at My Integrations and belongs to the correct workspace.

Database not found (404)

The database ID may be incorrect, or the integration has not been shared with the database. Open the database in Notion, click Share, and confirm the integration is listed. The database ID is the 32-character hex string in the URL before the ?v= parameter.

Authentication failed (401)

The integration token may be invalid or revoked. Go to My Integrations, find your integration, and regenerate the token. Update the token in Zeotap.

Property type mismatch

If a field value does not match the expected Notion property type (e.g., sending text to a number column), the page creation may fail for that row. Check your field mapping and ensure source data types are compatible with the Notion property types.

Rate limited (429)

Zeotap automatically retries rate-limited requests with exponential backoff. If syncs consistently hit rate limits, consider reducing the sync frequency or splitting large audiences into smaller batches.

Pages created but properties empty

Verify that the field names in your mapping exactly match the Notion database property names (case-sensitive). Properties not found in the database schema are silently skipped.

Update fails with “page not found”

When using update or upsert mode, the page_id field must contain a valid Notion page ID that belongs to the configured database. Verify the page exists and has not been deleted or moved to a different database.

MongoDB Optimizely