How to set up and configure Notion

May 21, 2024

This guide describes how to register a public Notion application (a.k.a. ‘integration') and configure it so that you can use the Unified API to query pages and databases.

Understanding Notion integrations: Internal vs Public

Before setting up your Notion integration, it's important to understand the two types of integrations Notion offers:

1. Internal Integrations: These are confined to a single workspace and are only accessible by members of that workspace. They're ideal for custom workspace enhancements.
2. Public Integrations: These are designed for a wider audience and can be used across any Notion workspace. They follow the OAuth 2.0 protocol for workspace access.

The main difference in terms of accessing user data is:

• For Internal Integrations, workspace members explicitly grant access to their pages or databases via Notion's UI.
• For Public Integrations, users authorize access to their pages during the OAuth flow, or by sharing pages directly with the integration.

For more information on the differences, refer to the Notion API Overview.

Setting up your Notion integration

The following steps outline how to register a public Notion integration:

1. Go to https://www.notion.so/my-integrations
2. Click on your integration (or create a new one)
3. Follow the steps to register a new Notion integration.
   1. Under Type, select Public.
   2. Under Redirect URIs, enter https://api.unified.to/oauth/code
4. Click Save.
5. Go to the configuration settings of your newly created integration and make a note of the OAuth Client ID and OAuth Client Secret.
6. Still under the configuration settings, make sure to select the permissions you need for your app under Capabilities e.g. read or update content.
7. Enter your OAuth credentials on https://app.unified.to/integrations/notion to activate the Notion integration.

Note: If you wish to create an Internal integration, most of the steps above can be skipped and you will need to enter your Internal integration token on app.unified.to instead. Instructions on how to find your internal token can be found here.

Querying databases in Notion

To query databases in Notion, you'll need to use our Unified KMS endpoint:

1. First, make sure you have a connection_id for your Notion integration.
2. Since database entries in Notion are technically pages, we'll use the List all pages endpoint:

   GET /kms/{connection_id}/page
   

API reference: List all pages

1. When querying pages in a database, you need to pass the database ID as the space_id parameter. For example:

   GET /kms/{connection_id}/page?space_id={database_id}
   
   

2. You can use additional parameters to filter and sort your results:
   • limit: Number of results to return (default: 100)
   • offset: Number of results to skip (default: 0)
   • updated_gte: Return only results updated on or after this date
   • sort: Sort by 'name', 'updated_at', or 'created_at'
   • order: Sort order ('asc' or 'desc')
   • query: Search query string
   • fields: Comma-separated list of fields to return

For example, to get the first 50 pages in a database, sorted by name in ascending order:

GET /kms/{connection_id}/page?space_id={database_id}&limit=50&sort=name&order=asc