How to create API integrations on Notion

intermediate 8 min read Updated 2026-03-18

Quick Answer

Creating API integrations in Notion involves setting up an internal integration through Notion's developer portal, obtaining an API token, and configuring your external application to communicate with Notion's databases and pages. You'll need to grant proper permissions and authenticate requests using the integration token.

Try Notion Full Notion Review

Prerequisites

Basic understanding of APIs and webhooks
Notion workspace with admin permissions
Developer account or app to integrate with
Understanding of authentication tokens

Step-by-Step Instructions

Create a New Integration

Navigate to https://www.notion.so/my-integrations and click + New integration. Enter your integration name, select the workspace you want to connect, and choose Internal as the integration type. Click Submit to create your integration.

Use a descriptive name for your integration to easily identify it later when managing multiple integrations.

Copy Your Integration Token

After creating the integration, you'll see an Internal Integration Token on the integration details page. Click Show and then Copy to save this token securely. This token starts with secret_ and is required for all API requests.

Store this token securely and never share it publicly - treat it like a password for your Notion workspace.

Configure Integration Capabilities

In the Capabilities section, select the permissions your integration needs:

Read content - allows reading pages and databases
Update content - allows editing existing content
Insert content - allows creating new pages and database entries

Save your changes by clicking Update.

Only enable the minimum permissions your integration actually needs to follow security best practices.

Share Database or Page with Integration

Open the Notion database or page you want to integrate with. Click the Share button in the top-right corner, then click Invite. Search for your integration name in the invite field and select it. Click Invite to grant access.

You must explicitly share each database or page with your integration - having the token alone isn't sufficient.

Set Up API Requests in Your Application

Configure your external application to make requests to Notion's API at https://api.notion.com/v1/. Include these headers in all requests:

Authorization: Bearer YOUR_INTEGRATION_TOKEN
Notion-Version: 2022-06-28
Content-Type: application/json

Always use the latest API version specified in Notion's documentation for access to the newest features.

Test Database Integration

Test your integration by making a GET request to retrieve database information using /v1/databases/{database_id}. You can find the database ID in the URL when viewing your database in Notion - it's the string of characters before any query parameters.

Use tools like Postman or curl to test your API requests before implementing them in your application code.

Implement Data Operations

Use the appropriate API endpoints for your needs:

POST /v1/pages - create new database entries
PATCH /v1/pages/{page_id} - update existing pages
POST /v1/databases/{database_id}/query - query database entries

Structure your JSON payload according to Notion's property types.

Reference Notion's API documentation for the exact JSON structure required for different property types like text, numbers, dates, and relations.

Monitor and Maintain Integration

Regularly check your integration's performance in the My integrations dashboard. Monitor API rate limits (3 requests per second) and implement proper error handling in your application. Update the Notion-Version header when new API versions are released.

Implement exponential backoff for rate limit errors and log API responses to troubleshoot issues effectively.

Common Issues & Troubleshooting

Getting 401 Unauthorized error

Verify your integration token is correct and included in the Authorization header as Bearer YOUR_TOKEN. Ensure the integration has been shared with the specific database or page you're trying to access.

Cannot find database or page

Check that the database/page ID is correct and that you've explicitly shared the resource with your integration through the Share menu. The integration won't have access even with a valid token unless explicitly granted.

Rate limit exceeded errors

Implement rate limiting in your application to stay under 3 requests per second. Add exponential backoff when receiving 429 status codes and consider batching operations where possible.

Properties not updating correctly

Verify that your JSON payload matches Notion's property type requirements exactly. Check the database schema using GET /v1/databases/{id} to confirm property names and types before updating.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official Notion website before purchasing.

Visit Notion View Notion Pricing