TemperStack
Find Tools
Intermediate8 min readUpdated Mar 18, 2026

How to create API integrations on Notion

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.

Prerequisites

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

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.
Tip
Use a descriptive name for your integration to easily identify it later when managing multiple integrations.
2

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.
Tip
Store this token securely and never share it publicly - treat it like a password for your Notion workspace.
3

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.
Tip
Only enable the minimum permissions your integration actually needs to follow security best practices.
4

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.
Tip
You must explicitly share each database or page with your integration - having the token alone isn't sufficient.
5

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
Tip
Always use the latest API version specified in Notion's documentation for access to the newest features.
6

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.
Tip
Use tools like Postman or curl to test your API requests before implementing them in your application code.
7

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.
Tip
Reference Notion's API documentation for the exact JSON structure required for different property types like text, numbers, dates, and relations.
8

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.
Tip
Implement exponential backoff for rate limit errors and log API responses to troubleshoot issues effectively.

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.

Related Guides

More Notion Tutorials

How to create your first workspace

How to add blocks using slash commands

How to build a simple task database

How to format text with markdown shortcuts

Other Tool Tutorials

A

Asana Tutorials

C

ClickUp Tutorials

D

Daino Notes Tutorials

Ready to get started with Notion?

Put this tutorial into practice. Visit Notion and follow the steps above.

Visit Notion →