Digital productivity tools are crucial for online collaboration and work-from-home setups. Even modest projects can have a surprising amount of people working on them, and businesses usually have many ongoing projects to address simultaneously. Thus, we’ve seen a rise in popularity in digital collaboration tools like Kanban boards; messaging programs like Slack; scheduling software like Buffer or Later; and collaborative design tools like Sketch or Figma.

Sometimes even getting our own stack to cooperate requires a whiteboard or flowchart, let alone adding other people into the mix. Third-party apps make this less complicated, but this can also leave you beholden to the third-party providers. This can quickly get expensive, as most of these providers involve monthly subscription fees.

This is where Notion comes into play.

For those who are not yet familiar, Notion is a popular open-source productivity tool that lets you create your own tools in nearly any way you can imagine. At its most basic, Notion is the best digital bullet journal currently available, allowing you to visualize and interact with your data in any way you see fit. These abilities help create mind maps and hierarchical lists.

That’s just the beginning of what Notion is capable of, however, when you add in the ability to invite remote collaborators. This makes this deceptively simple software capable of creating everything from to-do lists to custom content management systems to anything that a spreadsheet is capable of. Due to its flexibility, Notion has developed a nearly fanatical fanbase. The only thing Notion was missing, according to its users, was an API.

At the end of 2020, Notion users’ prayers were finally answered when a Notion API beta version was revealed. Those demands have proven to be well-justified, as you can do nearly anything with Notion when it’s powered by an API.

To offer you a glimpse of what the Notion API is capable of, we’ve put together a short tutorial on how to use the Notion API. This way, you can try it out for yourself and it into your workflows to see what it’s capable of.

Getting Started With Notion API

Getting started with the Notion API is relatively quick and simple. Start by setting up an account with Notion.

If you like, you can take a moment and read some of the documentation at developers.notion.com to familiarize yourself with the API structure. However, we’ll give you all the info you need in this tutorial, so it’s not necessary to learn how to use the Notion API.

To get started using the Notion API for yourself, begin by navigating to the My Integrations or click the My Integrations tab from the top-right corner of the Developers page. Click + New Integration and give your new integration a title.

Create An Integration

For this tutorial, let’s imagine we’re creating an integration to update a database any time a blog post is created. Let’s call this integration Blog.

In the Integration window, you can upload an image to use as a thumbnail. You can also choose which workspace you want to connect so you can create integrations for collaborative workspaces or your own projects, for instance.

Create the Integration, and you’ll be taken to a new page where you’ll see a field labeled Internal Integration Token. This is essentially your API key, so save this info someplace secure for later use.

Next, go back to your Notion workspace and create a new Page by selecting + Add A Page from the left-hand menu. Next, give it a title. We’ll call it Demo Database for the sake of simplicity. Next, create the database itself. Hit Enter to go to a blank cell and type /table and select Table - Full Page View. Note: commands in Notion are preceded by a /.

Setup The Database

For this tutorial, imagine you’re creating a custom Content Management System (CMS), and you want to have a table displaying the publishing status of each post. Start off by renaming the second column for its intended function. In this instance, we’re keeping track of the publishing status of our blog posts. We’re calling ours Status for the sake of simplicity.

Next, click the Header for the second column and choose the option for Multi-Select. This will reveal a second dropdown menu. Choose the Select option, which lets you specify the statuses you want to be available. We’re going to use Published, Drafts, and Writing. Enter each in the second column and then delete after hitting enter on each one.

Then you might add a third column for the featured image for the blog post. Title this column Image and click the Header, as before. Select the variable type URL, which will let you store the URL where the featured image is stored. You can do this for as many columns as you like, specifying the types of data each one will accept.

Once you’ve satisfied with your database, it’s time to make it accessible to the integration you’ve created. Select the Share tab from the top-right corner of the database page. Click Add people, emails, groups, or integrations. Select the name of the integration from the dropdown menu and click Invite. Now anytime you use that Internal Integration Token, you can interact with this particular database.

Query The API

Now let’s see how to actually query the data. We’re going to use Postman to make our API calls. In Postman, start by creating a new Request by selecting the New button to the right of My Workspace on the left side of the screen. Now we need to connect Postman to the API.

This requires a bit of understanding of how Notion is set up. Notion is organized into three levels: Databases, Pages, and Blocks. In the database we created, the whole object is the Database. Each of the individual cells are Pages. Elements of the individual pages are Blocks. For this tutorial, we’re going to connect the entire database.

To get the API address that Postman will query, start by taking a quick look at the API References. Select the Query Database option from the menu on the left. Here you will see the address https://api.notion.com/v1/databases/database_id/query.

To get the database_id, go back to your demo database. The database_id comes from the URL itself. To clarify, it’s the 32-digit string of numbers and characters to the right of the / and to the left of the ? character. Insert this ID in place of database_id.

Next, you need to supply the authenticator so Postman can access the database. In Postman, select the Authorization tab beneath the field for the API address. In the pulldown menu next to Type, choose Bearer Token. In the window that comes up, input the Internal Integration Token you saved. Now go ahead and submit that query to test your API query.

Unfortunately, you’ll notice this still gives you an error.

The query response should read “Notion-Version header failed validation: Notion-Version header should be defined, instead was undefined.” This means the query was expecting the Version to be defined. To find this, look at the Post Database Query documentation again. On the right, you should notice three lines of code in the cURL example, along the lines of:

  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H 'Notion-Version: 2021-08-16' \
  -H "Content-Type: application/json" \

Now go back to Postman and select the Headers table next to Authorization, where you input the API key. In the Key column, input Notion-Version. In the Value column, input the version you found in the documentation. Now try the query again. The query result should show your database in a JSON format.

Try Out the Notion API

If you want to see the Notion API in action, add a few items to your Demo Database. We just made three hypothetical objects called 1, 2, and 3 in the Name column.

To see what’s inside the database, you need to alter your API call slightly. Instead of just using the address specified by the database_id, you need to add /query to the end of your API call in Postman. You also need to change the HTTPS type from GET to POST. Now you should see the contents of your database return as a JSON object:

"title": [
                        {
                            "type": "text",
                            "text": {
                                "content": "2",
                                "link": null
                            },
                            "annotations": {
                                "bold": false,
                                "italic": false,
                                "strikethrough": false,
                                "underline": false,
                                "code": false,
                                "color": "default"
                            },
                            "plain_text": "2",
                            "href": null
                        }
                    ]
                }
            },
            "url": "https://www.notion.so/2-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        {

Seeing the JSON object should also help to illustrate how Notion formats its data as heavily nested JSON files. If you’re familiar with APIs, your wheels should already be turning about different ways you might interact with your raw data in pretty much any way you can imagine.

It also allows for Notion to act as the hub for virtually any task. For instance, there are already extensive integrations for Notion and Zapier, which allow you to create custom automated workflows in all sorts of creative ways.

There are pre-built integrations for Notion and Typeform, as well, if you want to connect online forms or surveys to a Notion database. There are extensive Automate.io integrations available for Notion, too.

Notion API: Final Thoughts

The world and how we do business were almost unbearably complex before the pandemic shifted more collaboration online. And if one thing is for certain, the world isn’t going to become less complex as time moves forward. Even something as simple as organizing a bake sale could involve an incredible amount of moving parts. You don’t want to be beholden to proprietary, inflexible software if you hope to achieve all that’s expected of you.

The Notion API couldn’t come at a better time, giving you everything you need to create your own custom integrations and automations using nearly any tool you can think of.