Table of Content

• Set Up a Notion Integration and Connect It to a Database
• Why this matters
• What you’ll need
• Step 1: Create your Notion Integration (secure API key)
• Step 2: Create the database you’ll connect
• Step 3: Share the database with your Integration
• Step 4: Grab the Database ID
• Step 5: Test connectivity (quick sanity check)
• Common pitfalls (and quick fixes)
• Optional: Minimal property schema you can copy
• Helpful resources

Set Up a Notion Integration and Connect It to a Database

If you want your tools to talk to Notion—whether that’s scripts, automations, or third‑party services—you’ll need a secure Integration with the right permissions, and a database that’s shared to it. The process is simple once you know the sequence. Below, you’ll set up the Integration, create your database, and connect the two in minutes.

Why this matters

• You control access with a scoped Integration token rather than sharing your personal account.
• Databases shared to the Integration become writable and readable via the Notion API.
• Clean boundaries mean safer automation, easier debugging, and fewer permission errors.

What you’ll need

• A Notion workspace with permission to create connections
• A desktop browser
• 10 minutes

Step 1: Create your Notion Integration (secure API key)

1. Go to Notion Integrations and click + New integration.
2. Name it clearly (for example, “Website Automation” or “Email Sync”).
3. Choose your workspace.
4. Capabilities: enable Read content and Insert content. Add Update content if you plan to edit existing pages.
5. Submit and copy the Internal Integration Token.
6. Store it securely in your secrets manager or environment variables. Do not paste it in code or docs.

Tip: Create one Integration per use case. It keeps scopes tidy and makes revocation painless.

Step 2: Create the database you’ll connect

1. In Notion, create a new page and choose Table to create a database.
2. Name it (for example, “Email Inbox” or “Website Leads”).
3. Add only the properties you need now. You can expand later. For example:
• Title: Name
• Date: Received
• Select/Status: Pipeline or Status
• Text: Notes
• URL: Source Link

Best practice: Keep property names human and consistent. Integrations work best with stable, descriptive names.

Step 3: Share the database with your Integration

1. Open the database page.
2. Click … (top right) → Add connections.
3. Search your Integration name and add it.
4. Confirm it appears under Connections on the page.

This is the critical permission step. Without it, API calls will return “object not found” even if your token is valid.

Step 4: Grab the Database ID

You’ll need the Database ID to target this specific database from code or a tool.

• Open the database as a full page.
• Copy the URL and extract the 32‑character ID after your workspace slug and before the view parameter.
• Keep it with your Integration token in your secrets manager.

Step 5: Test connectivity (quick sanity check)

Whether you use a code snippet, Zapier/Make, or a CLI, do a tiny test that doesn’t mutate much.

• Read test: list databases or retrieve database by ID.
• Write test: create a single page with only Title set.
• Verify the new row appears in Notion.

If reading works but writing fails, double‑check:

• The Integration has Insert/Update permissions
• The database is shared to the Integration (Step 3)
• Property names match exactly (case and spacing)

Common pitfalls (and quick fixes)

• 401 unauthorized: wrong or expired token. Regenerate and update your secret.
• 404 object not found: database isn’t shared to the Integration or the ID is wrong. Re‑share and retest.
• Property mismatch: payload uses “Status” but the database has “Pipeline.” Align names or map them.
• Over‑scoped Integrations: create a fresh Integration with only the capabilities you need.

Optional: Minimal property schema you can copy

• Name (Title)
• Date (Date)
• Status (Select: Inbox, In Progress, Done)
• URL (URL)
• Notes (Text)

Start small. You can always add properties and backfill later.

Helpful resources

• Notion Integrations: create and manage tokens
• Notion API docs: databases and pages endpoints
• Security best practices: storing and rotating secrets