How to Use Notion API to Sync With External Database

You want to sync data between Notion and an external database like PostgreSQL, MySQL, or Google Sheets. Manually copying entries is slow and error-prone. The Notion API lets you automate this sync so your Notion workspace always reflects the latest data from your external source. This article explains how to set up the Notion API, write a sync script, and handle common issues.

What the Notion API Does for External Database Sync

The Notion API is a RESTful interface that allows you to read and write data in your Notion workspace. To sync with an external database, you send HTTP requests from a script or application to the Notion API endpoints. The API returns JSON responses that you can parse and compare with your external data.

Before you start, you need three things:

• A Notion account with access to the workspace where your target database exists
• An internal integration created in the Notion Integrations settings page
• An external database you can query programmatically (for example, a SQL database with a Python connector)

The Notion API uses versioning headers. The current stable version is 2022-06-28. Always include the Notion-Version header in your requests. The API rate limit is three requests per second per integration. For large syncs, add delays or use batch processing to stay under this limit.

Steps to Set Up Notion API and Sync With an External Database

1. Create a Notion internal integration
   Go to https://www.notion.so/my-integrations. Click New integration. Give it a name, for example SyncDB. Select the workspace. Under Capabilities, ensure Read content, Update content, and Insert content are enabled. Click Submit. Copy the Internal Integration Secret token. Store it securely.
2. Connect the integration to your Notion database
   Open your Notion database page. Click the three-dot menu at the top right. Select Add connections. Find your integration SyncDB and click Connect. This grants the integration access to that specific database.
3. Get the database ID
   In your browser, open the Notion database page. Look at the URL. It looks like https://www.notion.so/workspace/abc123def456?.... The part after the workspace name and before the question mark is the page ID. If the URL contains a hyphen and a 32-character string, that string is the database ID. For example, in https://www.notion.so/MyDatabase-abc123def4567890abcdef1234567890, the ID is abc123def4567890abcdef1234567890.
4. Set up your development environment
   Install Python 3.8 or later. Create a virtual environment. Install the requests library with pip install requests. Also install your external database connector, for example pip install psycopg2-binary for PostgreSQL.
5. Write a Python script to query the Notion database
   Create a file named sync.py. Add code to send a POST request to the Notion API query endpoint. Use the token as a Bearer token in the Authorization header. The endpoint is https://api.notion.com/v1/databases/{database_id}/query. Parse the JSON response to get a list of existing pages.
6. Write code to fetch data from the external database
   In the same script, use your database connector to run a SELECT query. For example, with PostgreSQL: SELECT id, name, email FROM users. Store the results in a Python list of dictionaries.
7. Compare and sync the data
   For each record in the external database, check if a matching page already exists in Notion. Use a unique identifier property, such as an email or external ID. If the record exists, update the Notion page using the PATCH endpoint https://api.notion.com/v1/pages/{page_id}. If it does not exist, create a new page using the POST endpoint https://api.notion.com/v1/pages. For records that exist in Notion but not in the external database, optionally delete or archive the Notion page.
8. Run the script on a schedule
   Use a task scheduler like cron on Linux or Task Scheduler on Windows. For example, to run every hour, add a cron job: 0 /usr/bin/python3 /path/to/sync.py.

Common Sync Problems and Their Fixes

Notion API returns 401 Unauthorized

This error means the integration token is invalid or the integration is not connected to the database. Check that you copied the token correctly. Confirm the integration is listed in the database page under Add connections. Regenerate the token in the integrations settings if needed.

Rate limit exceeded (429 Too Many Requests)

The Notion API allows three requests per second per integration. If your script processes many records quickly, you will hit this limit. Add a delay between requests using time.sleep(0.4) to stay under three requests per second. For large datasets, process records in batches of 10 to 20 with a delay between batches.

Database ID not found or invalid

Double-check the database ID from the page URL. Make sure you are using the correct ID, not the workspace name or a page title. If the URL contains a hash or extra parameters, extract only the 32-character hex string. Test the ID by querying the database with a simple curl command before running the full script.

Property type mismatch when creating or updating pages

The Notion API expects specific JSON structures for each property type. For example, a title property requires an array with a text object, while a rich text property requires a similar array but with a different parent key. Review the Notion API documentation for the exact schema of each property type. Use the Retrieve a database endpoint to see the current property schema of your database.

Notion API Sync Methods Compared

Item	Python Script with requests	No-code tools (Zapier, Make)
Description	Custom script using the Notion API directly	Visual workflow builder with pre-built Notion connectors
Setup time	1-3 hours for a developer	15-30 minutes
Flexibility	Full control over logic, error handling, and data transformation	Limited to available triggers and actions
Cost	Free (except server or cloud function costs)	Free tier limited; paid plans start at $20/month
Rate limit handling	Manual delay and batch logic required	Built-in throttling in most tools
Best for	Complex sync logic, large datasets, custom schedules	Simple one-way syncs, non-technical users

Choose the Python script approach if you need bidirectional sync, complex data transformations, or full control over error recovery. Use no-code tools for quick setups where the external database also has a pre-built connector.

You can now sync an external database with Notion using the API and a Python script. Start by creating the integration and connecting it to your Notion database. Test the script with a small data set before automating it with a scheduler. For advanced use, explore the Notion API’s pagination feature to handle databases with more than 100 pages.