Create an integration
Make your first request to the Notion API.
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
- Sign up for a Notion account and create a workspace, or use an existing workspace
- Make sure you have Admin level access to the workspace
- Create at least one database in the workspace
- Install npm and node,js to use Notion’s JavaScript library
Step 1: Create an integration
A Notion integration lets you connect information in Notion to other software. To create your own integration:
- Visit https://www.notion.com/my-integrations in your browser.
- Click the
+ New integration
button. - Name the integration.
- Select the capabilities that your integration will have.
- 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.

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:
- Go to the database page in your workspace.
- Click the
•••
on the top right corner of the page. - At the bottom of the pop-up, click
Add connections
. - 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.

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
- 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=...
- 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"
}
}
- Run
npm install
to install the Notion client library, and then runnode index.js
to run the script:
npm install
node index.js
- 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
- Learn how to add an auth flow to your integration in the Authorization guide
Additional resources
Updated 2 months ago