Complete Guide to Building a Notion API Integration

Apr 4, 202425 minute read


Notion is an all-in-one workspace that combines notes, tasks, wikis, and databases to help individuals and teams organize their work and collaborate efficiently. As of 2021, Notion reported having over 20 million users worldwide.

What can you do with the Notion API?

The Notion API allows for interaction with several data models, each with its own set of capabilities for reading, updating, and inserting content. Here's a breakdown of what is possible for each data model:

  • Database Objects:

    • Read Content: Retrieve a database to access existing content.
    • Update Content: Update existing content within a database.
    • Insert Content: Create new content within a database.
  • Page Objects:

    • Read Content: Retrieve a page to access its content.
    • Update Content: Update properties of a page.
    • Insert Content: Create new pages.
  • Block Objects:

    • Read Content: Retrieve block children to access content within blocks.
    • Update Content: Update existing blocks.
    • Insert Content: Append new block children to a page or another block.
  • User Objects:

    • No User Information: Prevents access to any user information.
    • User Information Without Email Addresses: Access to user information excluding email addresses.
    • User Information With Email Addresses: Full access to user information including name, profile image, and email address.
  • Comment Objects:

    • Read Comments: Access to read comments from a Notion page or block.
    • Insert Comments: Ability to insert comments into a page or an existing discussion.

Each of these data models can be interacted with through specific API endpoints, allowing for a wide range of functionalities such as creating, reading, updating, and deleting content. The capabilities of an integration determine which actions it can perform and what information it can access within a Notion workspace. For example, an integration with "Read Content" capability can retrieve databases, pages, and blocks but cannot update or create new content. Similarly, an integration with "Update Content" capability can modify existing content but cannot create new content. The integration's capabilities are set during the authorization process and can be adjusted as needed [1].

Potential use cases

Based on the information provided in the sources, here are five potential use cases that can be enabled using the Notion API:

  • Automated Email Notifications: Develop an integration that sends automated emails based on changes or updates in a Notion database. This could be used for project updates, task reminders, or any other type of notification that needs to be sent out automatically.

  • Syncing with GitHub Issues: Create an integration that syncs GitHub issues to a Notion database. This allows for a centralized location to track and manage project tasks, bugs, and feature requests directly within Notion.

  • Link Preview Customization: Develop a Link Preview integration that customizes how links from your domain unfurl within Notion. This can enhance the presentation of content shared within Notion, making it more engaging and informative for users.

  • Identity Management Integrations: For enterprise workspaces, build integrations that manage user identities using SCIM (System for Cross-domain Identity Management) and SAML (Security Assertion Markup Language) for secure access and user management.

  • Data Integration with External Sources: Implement an integration that imports data from an external source into a Notion database. This could be used for syncing data from CRM systems, project management tools, or any other external data source into Notion for better organization and analysis.

Building with Notion's API

How to get a Notion developer account and API Keys?

To get a developer account for Notion and create an API integration, follow these steps:

  1. Create a Notion account if you don't have one already. Sign up at

  2. Ensure you are a Workspace Owner in the workspace you're using for integration purposes. If you're not the owner, create a new workspace for testing purposes.

  3. Go to Notion's integrations dashboard at and click on "+ New Integration" to create a new integration. Fill in the details for your integration, such as its name and internal/public status.

  4. After creating your integration, you'll be provided with an API secret. Keep this secret secure and do not share it publicly, as it is crucial for authenticating your API requests.

  5. Grant your integration explicit permission to read/write to specific Notion pages. Navigate to the Notion page you want your integration to access, click on the "More" menu in the top-right corner, and confirm the integration can access the page and all of its child pages.

By following these steps, you'll have a developer account for Notion and the necessary API keys to create an API integration and programmatically interact with your Notion workspace.

Open API Spec

API Explorer

Run Queries against the Notion API

Notion SDKs

TypeScript Logo

Typecript / Javascript

Top Notion SDK on NOM

Ruby Logo


Top Notion SDK on Rubygems

Python Logo


Top Notion SDK on PyPi

PHP Logo


Top Notion SDK on Packagist

C Sharp Logo


Top Notion SDK on NuGet

Notion API Details

What type of API does Notion provide?

Notion uses a REST API for its public API, allowing developers to interact with Notion workspaces programmatically.

Does the Notion API have webhooks?

The official Notion API does not explicitly mention webhooks in the provided documentation. Webhooks are typically used to receive real-time notifications about events happening in an application, such as new entries in a database or updates to a page. The Notion API documentation and guides focus on programmatic interaction with Notion's databases, pages, blocks, and users through REST API endpoints, enabling developers to create, read, update, and delete content within Notion programmatically.

For real-time updates or event-driven workflows, developers might need to implement polling mechanisms to periodically check for changes in Notion databases or pages. This approach, however, is not as efficient or immediate as webhooks, which would push updates to subscribed endpoints as soon as events occur.

Given the absence of webhooks in the official Notion API documentation, developers interested in real-time updates or event-driven workflows with Notion might need to explore alternative solutions or workarounds, such as:

  • Polling Notion's API: Regularly querying Notion's API for changes to databases or pages. This method is less efficient and can lead to higher API usage.
  • Third-party Integration Platforms: Using platforms like Zapier, which can automate workflows between Notion and other applications, to trigger actions based on events in Notion.
  • Custom Solutions: Developing custom solutions that use Notion's API to monitor changes and trigger actions in other systems.

For the most current and detailed information, it's recommended to consult the official Notion API documentation and developer resources directly, as the API's capabilities and features may evolve over time.

Rate Limits and other limitations

The Notion API has rate limits in place to manage the number of requests that can be made to its servers. The rate limit for incoming requests per integration is an average of three requests per second, with some bursts beyond the average rate allowed. When a rate limit is exceeded, the API will return a "rate_limited" error code (HTTP response status 429). Integrations should handle these rate limits by either slowing down the speed of future requests or by implementing a backoff strategy, such as using queues for pending requests. Additionally, the Retry-After response header value, which is set as an integer number of seconds, should be respected to avoid further rate limiting. It's important to note that Notion may adjust these rate limits in the future to balance demand and reliability, and distinct rate limits may be introduced for workspaces in different pricing plans.

Latest API Version

The most recent version of the Notion API is Notion-Version 2022-06-28.

Status Page

The most current status page URL for Notion is

Code Examples

Building authentication

Here are the steps to set up authentication for the Notion API:

  1. Obtain your Notion API credentials, including the client ID and client secret.

  2. Redirect the user to the Notion authorization URL to grant access to your application. Use the following CURL request:

    curl -X GET ''


  3. After the user grants access, Notion will redirect the user to your specified redirect URI with an authorization code in the query parameters.

  4. Exchange the authorization code for an access token by making a POST request to the Notion token endpoint. Use the following CURL request:

    curl -X POST '' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Accept: application/json' \ -d 'redirect_uri=YOUR_REDIRECT_URI&grant_type=authorization_code&code=AUTHORIZATION_CODE'

    Replace YOUR_REDIRECT_URI with your actual redirect URI and AUTHORIZATION_CODE with the code received in the previous step.

  5. Notion will respond with an access token and other relevant information. Store the access token securely for future API requests.

  6. Include the access token in the Authorization header of your API requests to authenticate and access protected resources. For example:

    curl -X GET '' \ -H 'Authorization: Bearer ACCESS_TOKEN'

    Replace ACCESS_TOKEN with the actual access token obtained in step 5.

By following these steps, you can set up authentication for the Notion API and securely access the API endpoints using the obtained access token.