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?

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:

• Sync a Contacts database with Google Contacts.
• Sync an Events database with Google Calendar.
• Aggregate expenses from multiple sources in an Expenses database.
• Collect form submissions in a Notion database.

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:

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

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.

• Create and publish your form in Typeform.
• In your Notion workspace, establish the database to receive submissions. It needs a property for each answer. For example, if your form asks for "First Name," the database needs a "First Name" property. The name of the property is unimportant, however, as you'll manually match the questions to the properties. Also be sure to prepopulate multiple choice options in a Select or Multi-Select property:
  
  
  
• Back in Typeform, when editing your form, click Connect at the top of the screen. Search for Notion and click Connect:
  
  
  
• In steps 1 and 2, authenticate the integration with your Typeform and Notion accounts.
• In the third step, select the database to receive submissions, then map each form question to the corresponding property:
  
  
  
• 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 Edit.

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

Zapier and Automate.io

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:

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.

Triggers

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.

Notion Triggers
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:

• If a meeting is added to the Events database...
• If a person is updated within the Contacts database...

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:

• If an order is created in Shopify...
• If a contact is updated in Google Contacts...

Internal Triggers
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:

• If it's the first day of the month...
• If an email is sent to a provided email address ...

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

Actions

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:

• If the trigger is an updated Salesforce contact, the action is to update the corresponding item in your Contacts database.
• If the trigger is a favorited song in Spotify, the action is to add the song to the corresponding database in Notion.

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:

• If the trigger is an updated item of the Contacts database, the action is to update the contact in Salesforce.
• If the trigger is a new item of the Meetings database, the action is to create an event in Google Calendar.

Internal Actions
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:

• Calculate the age of a new Salesforce contact from her birthday. You could then apply the calculated age to an "Age" property in the destination Notion database.
• Reformat the birthday from "MM/DD/YYYY" to "MMMM DD, YYYY." You could then include this friendlier format in the body of an email.

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:

• If the "Status" property is "Final"...
• If the "Complete" property is checked and the "Frequency" is not empty...

Configure Automate.io with Notion.

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.

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 Automate.io to access. That access will extend to their sub-pages and apply to all Bots you create with Automate.io.
5. Click Allow access, then Save.

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.

Configure Zapier with Notion.

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

1. Visit notion.so/my-integrations.
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. Automate.io

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.

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:

• Title (Multiple Choice)
• First Name (Short Text)
• Last Name (Short Text)
• Email Address (Email)
• Phone Number (Phone)
• Birthday (Date)
• Mailing Address (Long Text)

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

• Title (Select) → Title The Select options are preconfigured to match the Multiple Choice options in the form.
• First Name (Text) → First Name
• Last Name (Text) → Last Name
• Email (Email) → Email Address
• Phone (Phone) → Phone Number
• Birthday (Date) → Birthday
• Mailing Address (Text) → Mailing Address

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:

• In Typeform, when editing the form, click Connect at the top.
• Search for Notion and click Connect:
  
  
  
• Complete the authentication steps for Typeform and Notion.
• In Step 3, select the People database.
• We can then map each Typeform question to its corresponding database property:
  
  
  
• Click Save mapping.

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

Automate.io: 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 Automate.io, I can now automate it:

• In Automate.io, I choose Create a Bot.
• Within Select a Trigger app, I search for Notion, then select it under Add a new App:
  
  
  
• In the popup, I leave the default name, "Notion," and click Authorize:
  
  
  
• On the next screen, I select the proper workspace and click Select pages.
• I'm inclined to create Bots for databases throughout my workspace, so I select all pages, then click Allow access and Save:
  
  
  
• For the trigger, I choose Updated Item (Page).
  For a fully functional solution, you'd likely create another version of this Bot where the trigger is New Item (Page).
• For the database, I search for and select the People database.
• Automate.io then requests Created time and Last edited time properties from the database, so I create them, then hide them.
  These are within the Advanced options when creating a new property.
• With those properties in place, I select them where prompted in Automate.io.
  
  
  
• The action app is also Notion, which is now available under My Apps since it was configured for the trigger:
  
  
  
• The action is Update Item (Page).
• We want to use the Page ID of the page that triggered the update, which I choose by clicking +.
  
  
  
• We then want to populate the Full Name property with the first and last names, separated by a space. I click + and choose Page First Name from the triggered page. I add a space, then choose Page Last Name:
  
  
  
• With the configurations in place, I click Save, then toggle on the Bot.
• The next page offers for me to test the Bot, so I modify the email address of my sample contact, then click I'm Done.
• I see the "Full Name" property populated for my sample contact, and Automate.io confirms that the Bot is functional.

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 Automate.io.

Create a sample contact.

• In Google Contacts, apply the label to one contact to serve as sample data.

Configure the Zapier integration.

• To configure the Zapier integration for the first time, visit notion.so/my-integrations and choose + New integration.
• For the name, I like the format "Zapier → [Workspace]." The logo is optional, but be sure to choose the intended Associated workspace, then click Submit →.
• Alongside the token, click Show then Copy.

Grant Zapier access to the People database.

• While viewing the database, click the Share menu, then Add people, emails....
• Choose the new Zapier integration ("Zapier → [Workspace]") and click Invite.

Create the Zap.

• In Zapier, create a new Zap. For the name, I like the format "Google Contacts → Notion."
• For the trigger app, choose Google Contacts.
• For the trigger event, select New or Updated Contact, then click Continue:
  
  
  
• Select the intended Google Contacts account. Authorize it if you've yet to do so.
• Click Continue and Test trigger.
• Within the data, confirm that "Notion Sync" is paired with the "Groups" attribute, thus indicating your sample contact. Click Continue:
  
  
  
• For the action, search for and select "Filter by Zapier."
• Configure the filter to include contacts where "Groups" "Contains" "Notion Sync":
  
  
  
• Click Continue and confirm that "Your Zap would have continued."
• At the bottom, click + to add another action.
• Search for and select Notion.
• For the action event, choose Create Database Item, then click Continue.
• Click Sign in to Notion and paste the copied key:
  
  
  
• Click Yes, Continue, then Continue.
• For the database, choose the People database that we shared with the Zapier integration.
• For each fo the database properties, choose the corresponding value from Google Contacts:
  
  
  
  In our simple example, we leave phone numbers, addresses, etc., unlabeled and therefore choose the "undefined" version at this step. For "Full Name," you can combine the first and last names, with a space between them: "[Name First] [Name Last]."
• Click Continue, then Test & Continue.
• Confirm that you see your sample contact in your People database, then turn on your Zap.

Popular integrations.

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

• Reschedule or recreate recurring tasks.
• Aggregate contacts from Google Contacts, a CRM, an online store and a membership platform.
• Sync your calendar with an Events database.
• Send tasks to Notion by email and from voice assistants.
• Aggregate transactions from banks, online stores and other financial services.
• Automatically publish content to social media, blogs and websites.
• Automate communications at each sales stage, including follow-ups.
• Add photos taken on your phone to a Notion gallery.
• Add favorited songs to a Notion database.

---

Questions? Tweet @WilliamNutt.