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.
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.
Notion's API offers two overarching capabilities.
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:
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.
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
In most cases, those access levels can also be managed within the integrated service.
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.
Remember, only admins can configure integrations.
Connectat the top of the screen. Search for Notion and click
Save mapping. The integration is complete.
You can update the mapping at any time by revisiting the
Connect page, searching for Notion, clicking
•••, and choosing
In Notion, you'll see Typeform within the
Share menu of pages it can access.
Zapier and Automate.io 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 Automate.io. 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:
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 Automate.io.
You can trigger your Zaps and Bots by adding an item to a specified database in your workspace. In Automate.io, 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:
Zapier and Automate.io 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 Automate.io.
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:
Like internal triggers, Zapier and Automate.io 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:
Remember, only admins can configure integrations.
In the process of creating your Bot in Automate.io, you'll configure the Notion integration when you want to select Notion as your action app or trigger app.
Add a new App.
Allow access, then
For any Automate.io Bot, you can now choose Notion for your trigger or action. When doing so, Automate.io 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 Automate.io within the
Share menu for all pages it can access.
The Zapier configuration begins in Notion. Remember, only admins can configure integrations.
+ New integration.
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.
While Zapier and Automate.io 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 Automate.io 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 Automate.io.
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.
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.
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:
Select) → Title The
Selectoptions are preconfigured to match the
Multiple Choiceoptions in the form.
Text) → First Name
Text) → Last Name
Phone) → Phone Number
Date) → Birthday
Text) → Mailing Address
Title property, "Full Name," will be populated in the next example.
With the form published and the database complete, we can create the integration:
Connectat the top.
The integration is complete, and new form submissions appear automatically in the Contacts database.
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 Automate.io, I can now automate it:
Create a Bot.
Select a Trigger app, I search for Notion, then select it under
Add a new App:
Updated Item (Page).
New Item (Page).
Last edited timeproperties from the database, so I create them, then hide them.
Advancedoptions when creating a new property.
My Appssince it was configured for the trigger:
Update Item (Page).
Page IDof the page that triggered the update, which I choose by clicking
Full Nameproperty with the first and last names, separated by a space. I click
Page First Namefrom the triggered page. I add a space, then choose
Page Last Name:
Save, then toggle on the Bot.
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 Automate.io.
Create a sample contact.
Configure the Zapier integration.
+ New integration.
Associated workspace, then click
Grant Zapier access to the People database.
Add people, emails....
Create the Zap.
New or Updated Contact, then click
Continueand confirm that "Your Zap would have continued."
+to add another action.
Create Database Item, then click
Sign in to Notionand paste the copied key:
Yes, Continue, then
Test & Continue.
Here are some popular integrations facilitated by Zapier and Automate.io, many of which I'll demonstrate in forthcoming resources:
Questions? Tweet @WilliamNutt.