Notion API: The Ultimate Guide

Automate your workflow and free up time by leveraging the Notion API to turn your Notion Workspace into a true powerhouse. With the recently released Notion API, it’s now possible to integrate Notion with all your favourite productivity apps. Connect Notion to Google Calendar for easy planning, synch it with Todoist for Quick Capture or send emails to Notion in seconds. The best thing? You don’t need to know how to code to use the Notion API and most automations can be done for free with starter plans from Zapier and Automate.io.

Ready to design your perfect productivity system in Notion? Our upcoming course Supercharge Your Productivity is your first step to transforming your life and career.

Do you prefer video instructions to a written blog post? No worries, we’ve got you covered:

What is an API?

You can think of an API as a translator that helps move (and update) information between different apps.

Usually, information is contained within an app. Apps can’t just share information between each other. So you’re stuck using copy and paste or hiring expensive developers to customize a solution.

That’s pretty unnecessary work.

Imagine you run a company and department 1 reports to you expecting that you pass that information on to department 2 (wich happens to be located on the same floor as department 1) and vice versa.

You wouldn’t want to play messenger as the boss, now would you? You’d tell them to get their act together and communicate directly and only report information to you that’s destined for you.

With an API, you can do exactly that.

(Looking for more ways to leverage Notion? Check out our ultimate Notion tutorial or our comprehensive article on enhancing your workflow with other non-API Notion integrations.)

What can you do with the Notion API?

With the Notion API, you can (finally!) do three things:

1. Pull information from other apps into Notion – Example: add your gCal events to your Notion Calendar
2. Push information from Notion to other apps – Example: send an email directly out of Notion
3. Automate actions within Notion

The first two use cases for the Notion API sound obvious now that you know what an API does.

The third one is a bit of a surprise, but we’ll get to that in a moment. Essentially, you can connect Notion to itself to add some much needed functionality that hasn’t been natively integrated yet (yes, recurring tasks in Notion are finally here!).

How to use the Notion API

Generally speaking, there are three ways in which you can use the Notion API:

1. Create your own automation from scratch (if you know how to code)
2. Use a native integration (i.e. the app you want to connect automatically interacts with Notion)
3. Build your own automation using a no-code helper like Zapier or Automate.io

Let’s take a closer look at each step – but first, you need to set up our workspace for the Notion API.

How to prepare for any Notion API automation

The Notion API is currently in beta, so you need to do some preparation before you can start using it. You need to find your Notion API Token. Think of it as the “unique” address of your workspace. Just as in real life, you can only receive parcels if other’s know where to send them to.

Finding your Notion API Token for the first time might seem a bit tricky, but once you do it for the first time you’ll be set.

1. Head over to your workspace, click on Settings & Members and pick the brand new Integrations option (it will only appear if you’re the Admin of the workspace)
2. Select Create New Integration. This will open a new window showing My Integrations. Now, click New Integration, give it a name (we like “Unlock Notion API” because that’s the only thing it will do for now) and select the workspace you want to connect for your Zap.
3. Click Submit and then copy the Internal Integration Token
4. Save this Internal Integration Token (aka your Notion API Token) in your password manager or any other save space

Now there’s just one last step before you can get started. For Notion, collaborating with other people and using an integration work the same way. That means that you need to give the integration access to the page in your Notion workspace where it’s supposed to update information.

How to create your own Notion API automation from scratch using code

If you know how to code, then you can use the Notion API to write whatever integration you fancy. Going into details would be too much for this blog post, but luckily, the team over at Notion has got some great documentation for you to get started:

• check out the Notion API start page
• dive into the Notion API reference guide including JavaScript examples
• check out some case studies
• join Notion’s Platform Partner Program

How to use a native Notion API integration

Native Notion API integration means, that the developers of an app have build an official integration for you to use right off the bat without any additional work. Simply turn things on – and you’re good to go.

Right on release day, we got the first (of hopefully many) native Notion API integration with Typeform.

Typeform is a great and simple tool that lets you create beautiful surveys within minutes. And thanks to the native integration with Notion, you can send the results of your survey directly to your Notion Database. Here’s how:

1. Create your typeform survey as usual
2. Create a database in your Notion Workspace with corresponding properties for each answer you want to export. You don’t need to export all Typeform answers and the property name doesn’t have to match what you’re doing in Typeform. However, you need to make sure that each property has the same “type” as your Typeform question. If it’s an E-Mail field in Typeform, have an E-Mail formatted property in Notion. And if it’s single select or multiple choice, make sure to pre-populate all possible answers in Notion beforehand!
3. Head over to the Connect tab and pick Notion from the list of apps.
4. Next, you’ll be guided through a quick setup guide. And because it’s a native integration, you don’t even need to manually enter your Notion API Token.
5. Lastly, map your Typeform questions to the corresponding Notion database properties and you’re good to go

With time, more and more official API integrations will release to make our lives even easier. In the meantime, check out the next section to find out how to build pretty much any integration yourself in the meantime.

How to automate anything with the Notion API

You don’t need to know how to code to create pretty much any type of automation with the Notion API. The secret? Using a middle-man.

Zapier and Automate.io both provide you with simple visual builders to integrate Notion with a ton of other apps. Zapier calls these automations Zaps, Automate.io calls them Bots but they both work pretty much the same way. Here’s how to use them:

• Set up your Trigger. That’s the event that will kick off the automation. Most triggers will revolve around information being added to an app, but there are also a few other options. If you want to use Notion to start an automation, the most common Trigger would be New Database Item created. Zapier is currently limited to this Trigger for Notion, but Automate.io has a much richer set of triggers.

• Define your Action. What is supposed to happen once the trigger event takes place? Again, most of the time you would want to add the information that has been added to your Trigger App to a different app to create some very basic synching. Zapier currently offers the actions “Create Database Item”, “Update Database Item” and “Find Database Item” and Automate.io offers on top of that the option to “Add Content to Page”

Example: if you want to see all your gCal events in Notion, then “New Event” in gCal would be the Trigger and “Add Database Item” would be the Action of your automation.

Top Tip: browse Zapier and Automate.io for your most used apps and check out the triggers they offer to discover potential use cases for your workflow and the Notion API.

How to create recurring tasks in Notion via the API

You’ve heard it right – you can now add recurring tasks Notion.

Well, not exactly, but the next best thing: the Notion API. Both Zapier and Automate.io provide you with options to trigger an automation not based on information flowing into an app (our usual use case), but on a regular interval.

That means that you can simply set up a recurring task by setting a Schedule trigger and have Notion create the corresponding task.

For a more in-depth tutorial, check out this video by August Bradley.

Is the Notion API safe to use?

While the Notion API is super exciting and will make Notion even better than before, it’s important to remember that using any tool online comes with certain risks.

That doesn’t mean that the Notion API is not safe. But as fellow Notioneer It’s Gulia has pointed out, it’s important to be aware of the general risks.

It’s easy to get carried away by all the new opportunities and we’re sure to see a ton of amazing integrations build by the community. But remember to always apply standard security practises:

• Your Internal Integration Token is both the key and the address to your Notion Workspace. Just as in real life, you don’t want to just give out this token to anyone.
• Creating different Internal Integration Tokens might feel cumbersome, but just as with passwords, it reduces the potential damage if you ever leak one by accident
• Monitor the access rights of integrations carefully. Don’t just give an integration access to the top level of your Notion Workspace. Instead, keep it limited to the specific pages the integration actually needs to access.
• Don’t store anything in Notion you absolutely cannot afford to lose. That’s what encrypted and protected password managers are for.
• Use trustworthy sources when choosing your integrations

How to connect Todoist to Notion via API

Next, we’ll show you how to circumvent one of Notion’s most common critiques: Quick Capture is too slow.

Here’s how to integrate Todoist with Notion using Zapier.

What will the Zap do?

Once done, any new tasks that you add to your Todoist inbox will show up in your Notion Task Manager Database.

Step 1: Create new Zap

First, you need to make sure Zapier knows where to look for a new task.

To do so, you log into your Zapier Account, click Make A Zap and choose Todoist as your App Event.

Step 2: Define a Trigger Event

Next, you define your Trigger Event, i.e. the action that will start the automation.

You want to add new tasks that you create in Todoist to your Notion Task Manager, so you pick “New Incomplete Task”.

Step 3: Connect your Todoist Account to Zap

Connect your Todoist Account to Zapier to make sure Zapier has access to your tasks.

Step 4: Specify Trigger Event

As the last step for the trigger, you need to tell Zapier exactly where to look for new tasks.

Pick your Todoist Project best suited for synch with Notion.

You recommend picking your Inbox. That way, your Todoist Inbox is now also your Notion Inbox and all tasks will be synched in no time.

Step 5: Test your Trigger

Before moving on, Zapier would like to run a quick test. Before you do this, make sure that you have at least one unfinished task in the Project you picked in Step 4 (in this case: the inbox)

Step 6: Pick your action (in Notion)

Now for the fun part: pick Notion from the list of possible Action Apps.

Step 7: Tell Zapier what to do in Notion

So far, there are three things Zapier can do for us with the Notion API:

1. Create a Database item
2. Update a Database item
3. Find a Database item

You want to add new tasks to your Task Manager, so you opt for Nr. 1 “Create a Database Item”

Step 8: Connect your Notion Account

If this is your first time building a Zap with Notion, you need to find your Notion Token (basically the unique name of your workspace) to make sure Zapier updates pages in the right place.

1. Head over to your workspace, click on Settings & Members and pick the brand new Integrations option (it will only appear if you’re the Admin of the workspace)
2. Select “Create New Integration”. This will open a new window showing “My Integrations”. Now, click New Integration, give it a name (you like “Unlock Notion API” because that’s the only thing it will do for now) and select the workspace you want to connect for your Zap.
3. Click Submit and then copy the Internal Integration Token
4. Head back over to the Zap Setup, click on Notion Account → Connect New Account and copy the Token into the authentication field

You only have to do this once – next time, your Zap will remember your Notion API and you can skip this step.

Step 9: Specify Action

Now you just have to tell Zapier which information from Todoist should go where into your Notion Database.

There are two things to keep in mind before you start:

1. Integrations work the same way as sharing a page with other people. That means, you need to grant the integration access to the specific page containing your task manager.
2. Our Action is called: Create new Database item. That means, you need to have a database for your tasks set up and can’t just use a page with simple checkboxes

If your Task Manager is set up accordingly (shared with the integration & a database), simply pick the name from the drop down menu “Database”.

This will load all of fields (i.e. properties) located in your Task Manager Database. For this demonstration, we’ve used a rather simple one and leave the complex stuff to our trusted Notion formulas.

Now, assign each property the corresponding information from Todoist.

Because you want to use Todoist just as a quick capture tool for new tasks in Notion, you leave all fields empty except for the main field.

Step 10: Test your Action

Test your Zap & you’re good to go!

One last thing: Zapier currently synchs every 2 minutes with the Notion API, so don’t worry if new tasks don’t show up instantaneously. But even with that slight delay, this automation will make adding tasks to Notion just so much easier and faster!

How to send emails to Notion via the API

Once done, any task that you send to a specific email address will show up in your Notion Task Manager Database. To mix up our examples we’ll demonstrate using Automate.io.

What will the Bot do?

You want to be able to send or forward an email to Notion and grab the subject line as a new task in our task manager.

Step 1: Create new Bot

Log into your Automate.io account and click Create new Bot.

Step 2: Define a Trigger

Unlike before, you won’t be using a separate app for this automation. Instead, you opt for the Email option. Automate.io will now generate a unique email address for us. Every time a mail is send to this address, the automation will trigger.

Remember to click Get Email Address and copy your unique email address for later use of the bot

Step 3: Pick an Action App

Now, let’s head over to the Action part of the automation. You want to add the emails as tasks to Notion, so you pick Notion from the list of possible apps.

Luckily, Automate.io has a very smooth verification process and you don’t need our Internal Integration Token. Simply follow the instructions on the screen and grant Automate.io access to the page with your task manager.

Step 4: Tell Automate.io what to do in Notion

Whenever you send a mail to your unique address, you want to create a new task. That means you need to pick Add Database Item from the list of possible Actions within Notion.

Next, it’s time to select the Database (our Task Manager). Make sure to have this database set up before you start creating your automation in Automate.io. For this simple demonstration, we’re using a task manager with only two properties (Task Name & a Select Field).

Step 4: Map email fields to Notion properties

Now that we’ve picked the Database, all that’s left to do is tell Automate.io where the information from the email should go.

First, you specify that the text body of the mail (what you write within the mail) is added as content of the newly created task.

Next, you set the Tag to “E-Mail”. This is purely optional, but it can be helpful to tag tasks that came in via email in case you want to apply specific views to your task database later. If not, feel free to leave this empty.

Lastly, you want to pull in the subject line as the name of the newly created task.

Step 5: Test your Bot

Click Save Bot and test it by sending a mail to your unique email address. After a few moments, the email should appear in your task database.

Tips & Tricks

• save your unique email address as a contact to quickly forward mails to Notion
• You could easily integrate this with Siri & Apple Shortcuts to send tasks via voice commands to Notion
• Combine this automation with gMails powerful filters to automatically forward specific mails to your unique address to add them to Notion

How to synch Google Calendar with Notion via API

And finally, here’s how to keep your Notion calendar up to date with what’s happening in Google Calendar. We’re using Zapier again, but Automate.io would work just the same.

What will the Zap do?

Whenever a new event is added to your Google Calendar, the event will show up in our Notion Calendar.

Step 1: Create new Zap

First, you need to make sure Zapier knows where to look for a new event.

To do so, you log into your Zapier Account, click Make A Zap and choose Google Calendar as your App Event.

Step 2: Define a Trigger Event

Next, you define your Trigger Event, i.e. the action that will start your automation.

Here, the first instinct would be to pick “New Event” as the trigger. After all, you want to have new events show up in Notion. And while this generally works, it does not support recurring events in Google Calendar right now. So if you use recurring events at all, you recommend that you go with Event Start.

What’s the difference? Events won’t be added to your calendar based on their creation, but based on whether they happen within the next x weeks.

Pick a timeline that suits your workflow. We like 4 weeks to see the whole upcoming month.

Step 3: Connect your Google Calendar Account to Zap

Connect your gCal Account to Zapier to make sure Zapier has access to your events.

Step 4: Specify Trigger Event

As the last step for your trigger, you need to tell Zapier exactly which events should trigger the automation.

You can pick as many calendars within your gCal account as you want for synching. Use the Time Before and Time Before (Unit) to specify the time window for events to appear (four weeks in this case).

You leave Search Term empty because you want to synch all events.

Step 5: Test your Trigger

Before moving on, Zapier would like to run a quick test to make sure everything is set up correctly.

Step 6: Pick your action

Pick Notion from the list of possible Action Apps.

Step 7: Tell Zapier what to do in Notion

You want to add the new events to our Notion Calendar, so you opt for Nr. 1 “Create a Database Item”

Step 8: Connect your Notion Account

If this is your first time building a Zap with Notion, you need to find your Notion Token (basically the unique name of your workspace) to make sure Zapier updates pages in the right place.

If you’ve done this already, then you can simply skip this step.

1. Head over to your workspace, click on Settings & Members and pick the brand new Integrations option (it will only appear if you’re the Admin of the workspace)
2. Select “Create New Integration”. This will open a new window showing “My Integrations”. Now, click New Integration, give it a name (we like “Unlock Notion API” because that’s the only thing it will do for now) and select the workspace you want to connect for your Zap.
3. Click Submit and then copy the Internal Integration Token
4. Head back over to the Zap Setup, click on Notion Account → Connect New Account and copy the Token into the authentication field

You only have to do this once – next time, your Zap will remember your Notion API and you can skip this step.

Step 9: Specify Action

Now you just have to tell Zapier which information from Google Calendar should go where into your Notion Database.

One thing to keep in mind before you start:

Integrations work the same way as sharing a page with other people. That means, you need to grant the integration access to the specific page containing your task manager.

If your Notion Calendar is set up accordingly (shared with the integration), simply pick the name from the drop down menu “Database”.

Now, assign each property the corresponding information from Google Calender.

Step 10: Test your Action

Test your Zap & you’re good to go!

Remember: Zapier currently synchs every 2 minutes with the Notion API, so don’t worry if new events don’t show up instantaneously.

Tips & Tricks

• If you work a lot in Notion and want to use Google Calendar only to display the events, then you could simply reverse the Zap to have events from Notion be added to gCal
• If you change events a lot after creating them, you would want to add a second Zap responsible for updating events. Check out this great video by August Bradley that explains the setup.

Case Study: How we use the Notion API at RadReads

At RadReads, we make use of the Notion API to streamline our own workflows while delivering a delightful experience to our students. You can check out the full Notion automation case study in our Notion For Business Guide.

Best integrations for Notion API

Want even more? Here’s some inspiration:

• Send a mail depending on updates to a Notion Database (for example notify someone when you add or finish a task)
• Using Slack over email? No problem, you could also post in a channel without ever leaving Notion
• Stop copy-pasting information from emails into Notion and let the Notion API do the work instead
• Missing graphs in Notion? Just set up an automatic export to Google sheets and work from there!

(A huge thanks to Matthias Frank for collaborating to write this post.)