Notion VIP Logo
BulletproofA-to-ZConsultingThe Streamline

Notion Explained: The API Debut

Watch the video or read the post:

Despite Notion's many competitive advantages, its absent API deterred many potential users. From the earliest days of Notion, users have pleaded for an API. The topic emerged daily across online conversations.

Nonetheless, it seemed the API would never arrive. Each hint of an impending release would be followed by days, weeks, months without an update.

The wish finally came true on May 13, 2021, when the API entered public beta. With that milestone, Notion unleashed a world of new possibilities and took another sizable step ahead of competing apps.

In this overview, I explore the fundamentals of the API and how to use it, demonstrated by a few simple examples. Moving forward, I'll walk through more complex implementations of the API, so stay tuned to the Notion VIP newsletter and @WilliamNutt.

What's an API?

Notion API

An application programing interface, or API, allows an app to integrate with other apps. Through these integrations, apps can exchange information and make updates.

Apps that schedule social media posts, for example, use the APIs of Twitter and Facebook. Accounting apps use your bank's API to import financial transactions. Tools that merge cloud drives use APIs from Dropbox and Google Drive.

Any time you see "sync" or "integration" within a service, it likely involves an API.

What can you do with the Notion API?

Notion's API offers two overarching capabilities.

Exchange information with other apps.

When information is added or updated in another app, the same change can occur automatically in a Notion database. Conversely, if Notion is modified, the API can update the other app. Here are a few examples:

Automate actions.

Rather than integrating Notion with other apps, you can automate actions within your workspace. Users have long requested recurring tasks, and with the API, you can now recreate or reschedule a task when it's completed. Other example automations include emailing a report each month and updating a "Next Birthday" property each year.

How to use the Notion API.

Developers access the API; users access integrations.

APIs are typically used by developers, who develop integrations with their apps. Everyday users then configure those integrations without needing to code.

In Notion, integrations function like a special type of user. Once an admin has added an integration to a workspace, members can grant it access to a page from the page's Share menu:

Notion Integration Access

In most cases, those access levels can also be managed within the integrated service.

The first three integrations.

Notion partnered with three services to offer official integrations at the API's debut. Numerous others are now actively under development.


Typeform allows you to create beautiful, interactive online forms. With the Notion integration, you can send responses directly to a database in your workspace.

Configure Notion's Typeform integration.

Remember, only admins can configure integrations.

You can update the mapping at any time by revisiting the Connect page, searching for Notion, clicking •••, and choosing Edit.

In Notion, you'll see Typeform within the Share menu of pages it can access.

Zapier and

Zapier and allow everyday users to create custom integrations with apps before those apps offer official integrations. These services are commonly referred to as "translators" of APIs, as they manifest the capabilities of an API in a visual interface.

Users create "Zaps" in Zapier and "Bots" in Each Zap and Bot includes a "trigger," followed by one or more "actions" to take when the trigger's conditions are met. In other words:

If [trigger], do [actions].

For each Zap and Bot you create for Notion, either the trigger or action will occur in Notion, if not both.


Your Zaps and Bots can be triggered when conditions are met within Notion, within another app, or within "monitors" configured internally in Zapier or

Notion Triggers
You can trigger your Zaps and Bots by adding an item to a specified database in your workspace. In, you can also trigger a Bot by updating an item. For example:

Triggers from Other Apps
Alternatively, you can create triggers from other apps, in which case at least one of your actions will occur in Notion. For example:

Internal Triggers
Zapier and each offer custom triggers that are independent of third-party apps. With these "internal apps," you can create recurring schedules, receive emails, catch webhooks and more. For example:

When using internal triggers, at least one of your actions will occur in Notion.


When a Zap or Bot is triggered, it executes one or more actions. Those actions can occur in Notion, other apps, or internally within Zapier or

Actions almost always reference information provided by the trigger, such as the ID of the updated page or the traits of a new contact.

Actions in Notion
Your Notion-based actions will typically include adding and updating database items. For example:

Actions in Other Apps
When your Zap or Bot is triggered by Notion, you'll often want the action to occur in another app. For example:

Internal Actions
Like internal triggers, Zapier and each offer custom actions that are independent of third-party apps. Sending an email is one common example.

These internal actions are often an interim step in a series of actions. You can reformat and perform calculations on information provided by the trigger, then pass the new value to the next action. For example:

You can also filter information provided by the trigger, then proceed only if certain conditions are met. Zapier supports "paths," where you can specify two series of actions: one if the filter is true; the other if the filter returns false. Here are two example filters:

Configure with Notion.

Remember, only admins can configure integrations.

Add Notion to

In the process of creating your Bot in, you'll configure the Notion integration when you want to select Notion as your action app or trigger app.

  1. In the app-selection dropdown, search for Notion. Choose it under Add a new App.
  2. In the popup, click Authorize.
  3. Choose the workspace you'd like to connect, then click Select pages.
  4. Check the top-level pages you'd like to access. That access will extend to their sub-pages and apply to all Bots you create with
  5. Click Allow access, then Save.

For any Bot, you can now choose Notion for your trigger or action. When doing so, often requests Created time and Last edited time properties in your connected database, in which case you can create them, then hide them from all views.

After initializing the integration, you'll see within the Share menu for all pages it can access.

Configure Zapier with Notion.
Add Zapier to Notion

The Zapier configuration begins in Notion. Remember, only admins can configure integrations.

  1. Visit
  2. Click + New integration.
  3. Give it a name. I like the format "Zapier → [Workspace]."
  4. Select the workspace for this Zapier integration.
  5. Click Submit →.
  6. That will provide a token. Store it somewhere handy.
  7. In Notion, grant the integration access to the necessary pages of your workspace: at the top of the pages, click Share, then Add people.... Choose the integration from the bottom list and click Invite. Remember, page access extends to all inner pages, so I recommend sharing a top-level page that contains all databases your Zapier integration will need to access.
  8. When choosing Notion for the first time in Zapier, you'll be prompted to authenticate the integration and paste your token.
Zapier vs.

While Zapier and generally offer the same capabilities, there are some nuanced differences. Zapier supports more apps, but it's more expensive and cumbersome to configure. A considerable advantage of is the ability to trigger Bots when databases are updated, whereas Zaps are only triggered from new database entries.

You can make a detailed comparison using the pricing pages of Zapier and

Optimize your workspace for the API.

If you're familiar with my resources, you know I approach every Notion workspace with a core tenet. In the simplest terms, it is:

Use databases, not pages.

Long before the API, this strategy afforded numerous benefits. It's the crux of my Bulletproof methodology, the most widely employed framework and top-selling template among Notion users. The API makes the approach even more advantageous.

Among all example API implementations, you'll notice a constant: Databases. Powered by the API, Notion integrations function best when applied to databases. Each configuration matches a database property to a value in the integrated app for a seamless information exchange. The "First Name" of a Salesforce contact, for example, maps to the "First Name" property in a Contacts database.

I explore this database-centric strategy further in a recent post dedicated to API optimization.

Example configurations.

Below, I detail the configurations for three simple integrations for managing contacts—one for each of the first three services. In subsequent posts, I'll demonstrate more complex configurations, including two-way syncing and conditional paths.

Typeform: Send form submissions to a Notion database.

I use Typeform to collect contact information from family, friends and business associates. It contains seven fields:

In Notion, a People database contains a property for each of the form fields:

Notion Database for Typeform

The Title property, "Full Name," will be populated in the next example.

With the form published and the database complete, we can create the integration:

The integration is complete, and new form submissions appear automatically in the Contacts database. Populate the Title property.

In many of my Notion databases, I like to populate the Title property by combining other properties. For example, the Title property of my Contacts database is "Full Name," which combines "First Name" and "Last Name."

In the past, I've used a formula to combine the properties, which I copy and paste into the Title property. With, I can now automate it:

Zapier: Add Google Contacts to a Contacts database.

In Google Contacts, when I label a contact "Notion Sync," I want that contact added to my Contacts database in Notion. For this, we'll use Zapier, for which configuration is a bit more cumbersome than

Create a sample contact.

Sample Google Contact for Notion

Configure the Zapier integration.

Grant Zapier access to the People database.

Share Notion Database with Zapier Integration

Create the Zap.

Popular integrations.

Here are some popular integrations facilitated by Zapier and, many of which I'll demonstrate in forthcoming resources:

Questions? Tweet @WilliamNutt.

All-in on
the all-in-one
productivity app.
Subscribe →