View my integrations

Create an integration

Make your first request to the Notion API.

Suggest Edits

You can use the Notion API to extend pages and databases into the tools that you use every day.

In this tutorial, you’ll use the Notion API to add an item to a Notion database. After you’ve finished, you’ll know how to:

  • Create an integration
  • Share a database with your integration
  • Save the database ID
  • Add an item to the database

📘

If you already have something in mind that you’d like to build, then head to the Notion reference documentation. You can also explore FAQs, more in-depth code examples, or a TypeScript starter repo.

Before you begin

Step 1: Create an integration

A Notion integration lets you connect information in Notion to other software. To create your own integration:

  1. Visit https://www.notion.com/my-integrations in your browser.
  2. Click the + New integration button.
  3. Name the integration.
  4. Select the capabilities that your integration will have.
  5. Click Submit to create the integration.

On the next page, you’ll find your Notion integration token, also called an API key. You’ll need this token to make requests to the Notion API. To retrieve your token after you leave this page, return to https://www.notion.so/my-integrations and click View integration.

The integration has been added to the workspace, so any member can share pages and databases with it. There’s no requirement to be an Admin to share information with an integration.

929

Creating a Notion integration

Step 2: Share a database with your integration

Now that you’ve created an integration, you need to grant it access to a database. To keep your information secure, integrations don't have access to any pages or databases in the workspace at first. You must share specific pages with an integration in order for the API to access those pages. To share a database with your integration:

  1. Go to the database page in your workspace.
  2. Click the •••on the top right corner of the page.
  3. At the bottom of the pop-up, click Add connections.
  4. Search for and select your integration in the Search for connections... menu.

Your integration now has permission to edit the database.

Step 3: Save the database ID

You’ll need the database ID to edit the database using your Notion integration.

To get the database ID, copy the URL of your Notion database. If you're using an inline database, then make sure you're viewing the database as a full page. If you're using the Notion desktop app, then click Share and select Copy link to find the database URL.

The database ID is the string of characters in the database URL that is between the slash following your workspace name (if you named it) and the question mark. The ID is 32 characters long, containing numbers and letters.

1502

Notion Database ID

Copy the ID and paste it somewhere that you can easily find it for the next step.

Step 4: Add an item to the database

Using Notion’s JavaScript library

  1. Create a new directory and save the Notion API key from Step 1and the database ID from Step 3 as environment variables. Use the following command, swapping in your own secret keys:
mkdir notion-example
cd notion-example
export NOTION_KEY=secret_...
export NOTION_DATABASE_ID=...
  1. Add the following index.js and package.json files to your directory:

index.js:

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_KEY })

const databaseId = process.env.NOTION_DATABASE_ID

async function addItem(text) {
  try {
    const response = await notion.pages.create({
      parent: { database_id: databaseId },
      properties: {
        title: {
          title:[
            {
              "text": {
                "content": text
              }
            }
          ]
        }
      },
    })
    console.log(response)
    console.log("Success! Entry added.")
  } catch (error) {
    console.error(error.body)
  }
}

addItem("Yurts in Big Sur, California")

package.json:

{
  "name": "notion-example",
  "type": "module",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "dependencies": {
    "@notionhq/client": "^1.0.1"
  }
}
  1. Run npm install to install the Notion client library, and then run node index.js to run the script:
npm install
node index.js
  1. Return to the Notion database. The new item has appeared!

Using cURL

To make the HTTP request directly, use cURL. Replace the placeholders in the following example with your Notion API key and database ID, and run the command from the terminal:

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2021-08-16" \
  --data "{
    \"parent\": { \"database_id\": \"$NOTION_DATABASE_ID\" },
    \"properties\": {
      \"title\": {
        \"title\": [
          {
            \"text\": {
              \"content\": \"Yurts in Big Sur, California\"
            }
          }
        ]
      }
    }
  }"

Visit the database page in Notion, and a new item has has appeared! You’ll also find the following output in your terminal:

{
  "object": "page",
  "id": "91937806-1a95-42e4-a3c6-340d9e002a73",
  "created_time": "2022-08-05T22:31:00.000Z",
  "last_edited_time": "2022-08-05T22:31:00.000Z",
  "created_by": {
    "object": "user",
    "id": "NOTION_USER_ID"
  },
  "last_edited_by": {
    "object": "user",
    "id": "NOTION_USER_ID"
  },
  "cover": null,
  "icon": null,
  "parent": {
    "type": "database_id",
    "database_id": "NOTION_DATABASE_ID"
  },
  "archived": false,
  "properties": {
    "Tags": {
      "id": "%3BJin",
      "type": "multi_select",
      "multi_select": []
    },
    "Name": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Yurts in Big Sur, California",
            "link": null
          },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Yurts in Big Sur, California",
          "href": null
        }
      ]
    }
  },
  "url": "NOTION_URL"
}

📘

No new item appearing in the database?

  • First, try reloading the browser or app.
  • Read your terminal output. If the message starts with {"object":"error",..., then there's something wrong with your request. Double check that your API token and database ID are correct.
  • Check that you've performed the tutorial steps correctly, and try again.
  • If you're still experiencing an issue, then click “Help” in the footer or join our developer community on Slack.

Next steps

Additional resources

Updated 2 months ago