APIs & Integrations
Notion
Overview
Pre-built tooling
✅ Authorization
✅ Authorization
✅ Read & write data
✅ Read & write data
| Tools | Status |
|---|---|
| Pre-built integrations | ✅ |
| API unification | ✅ |
| 2-way sync | ✅ |
| Webhooks from Nango on data modifications | ✅ |
| Real-time webhooks from 3rd-party API | 🚫 (time to contribute: <48h) |
| Proxy requests | ✅ |
✅ Observability & data quality
✅ Observability & data quality
| Tools | Status |
|---|---|
| HTTP request logging | ✅ |
| End-to-type type safety | ✅ |
| Data runtime validation | ✅ |
| OpenTelemetry export | ✅ |
| Slack alerts on errors | ✅ |
| Integration status API | ✅ |
✅ Customization
✅ Customization
| Tools | Status |
|---|---|
| Create or customize use-cases | ✅ |
| Pre-configured pagination | ✅ |
| Pre-configured rate-limit handling | 🚫 (time to contribute: <48h) |
| Per-customer configurations | ✅ |
Pre-built integrations
Contents
Contents
Databases
Databases
| Endpoint | Description | Readme |
|---|---|---|
GET /databases/single | Fetch a specific Notion database by passing in the database id. This action fetches the database and outputs an object. Note that this should be used for small databases. | 🔗 |
POST /databases/row | Create a new row in a specified Notion database. The properties are mapped to Notion-compatible formats based on the database schema. Supported property types include: - title (string): Creates a title property.- select (string): Creates a select property.- multi_select (array of strings): Creates a multi-select property.- status (string): Creates a status property.- date (string or object): Supports ISO date strings or objects with a start field.- checkbox (boolean): Creates a checkbox property.- number (number): Creates a number property.- url (string): Creates a URL property.- email (string): Creates an email property.- phone_number (string): Creates a phone number property.- rich_text (string): Creates a rich text property.- relation (array of IDs): Creates a relation property. | 🔗 |
GET /databases | Sync a database content with each row as an entry. Store the top level database information in the metadata to be able to reconcile the database | 🔗 |
Pages
Pages
| Endpoint | Description | Readme |
|---|---|---|
GET /pages/single | Fetch a specific page in Notion by passing a pageId. This action fetches a page, and its content and converts it into a full markdown. It transforms images, tables, uploaded files, etc., into their markdown counterparts, providing a complete markdown. | 🔗 |
Users
Users
| Endpoint | Description | Readme |
|---|---|---|
GET /users | Fetches a list of users from Notion | 🔗 |
Not seeing the integration you need? Build your own independently.
Access requirements
| Pre-Requisites | Status | Comment |
|---|---|---|
| Paid dev account | ✅ Not required | Free, self-signup for a Notion account. |
| Paid test account | ✅ Not required | Free Notion account can be used for testing. |
| Partnership | ✅ Not required | |
| App review | ✅ Not required | Only required for apps published to the Notion App Store. |
| Security audit | ✅ Not required |
Setup guide
1
Create a Notion account
If you don’t already have one, sign up for a Notion account.
2
Create a new integration
- Go to My Integrations in your Notion account.
- Click + New integration.
- Fill in the integration details (as shown in the screenshots):
- Integration Name: Enter a name for your integration
- Associated workspace: Select the Notion workspace
- Type (required for Oauth): Select Public
- Company name: Enter your company name
- Website: Enter your company website URL
- Tagline: A short description of your integration
- Privacy Policy URL: Link to your privacy policy
- Terms of Use URL: Link to your terms of service
- Email: Developer contact email
- Logo: Upload a 512×512 image
- Redirect URIs: Add
https://api.nango.dev/oauth/callback - Notion URL for optional template: (Optional) Add a public Notion page URL if you want to offer a template
- Click Save.
3
Obtain API credentials
- After saving, click Configure integration settings. You’ll then be redirected to your integration’s page.
- Under the Configuration tab, you’ll find both your: OAuth Client ID and OAuth Client Secret. Save these credentials securely as you’ll need them when configuring your integration in Nango.
- Under the Capabilities section, select the permissions your integration requires. These will be displayed to users.
4
Next
Follow the Quickstart.
Need help getting started? Get help in the community.
Useful links
Contribute useful links by editing this page
API gotchas
- The Notion OAuth API doesn’t support refreshing tokens, and so doesn’t return a refresh token. The access token never expires.
- When creating a Notion OAuth app, it is set to Internal by default. You need to make it Public to initiate an OAuth flow with users. Only then will you be able to obtain the OAuth client ID/secret and register your callback URL.
- No OAuth scope is required by default for Notion integrations.
- After authorization, users need to explicitly share specific pages or databases with your integration before you can access them.
- Notion has rate limits that vary by endpoint.
Contribute API gotchas by editing this page