Connect a Notion database

Notion lets PageOptimized send approved content tasks into a database your team uses for production.

PageOptimized verifies the database by calling Notion's database API, then creates pages with task properties when you sync.

Official Notion references:

• Getting started: https://developers.notion.com/guides/get-started/quick-start
• Internal connections: https://developers.notion.com/guides/get-started/internal-connections
• Retrieve a database: https://developers.notion.com/reference/retrieve-a-database

Before you start

1. Confirm you are a Notion workspace member who can create integrations.
2. Create or choose the database where PageOptimized content tasks should land.
3. Open PageOptimized in another tab.
4. Go to the project.
5. Open Publishing > Connections.
6. Find the Notion card.

Step 1: create the Notion integration token

1. Open https://www.notion.so/my-integrations.
2. Click New integration.
3. Enter a name, such as PageOptimized.
4. Choose the workspace that owns the content database.
5. Select the Notion API capability when Notion asks for capabilities.
6. Give the integration permission to read content.
7. Give the integration permission to insert content.
8. Give the integration permission to update content if your workflow will update synced tasks later.
9. Save or create the integration.
10. Copy the internal integration secret. It usually starts with secret_.
11. Store it somewhere secure until you paste it into PageOptimized.

Step 2: prepare the Notion database

PageOptimized currently writes these database properties:

1. Name: title property.
2. Keyword: text property.
3. Status: select property.
4. Owner: text property.
5. PublishDate: date property.

To prepare the database:

1. Open the Notion database as a full page.
2. Confirm there is a title property named Name.
3. Add a text property named Keyword if it does not exist.
4. Add a select property named Status if it does not exist.
5. Add common status options, such as planned, draft, review, approved, and published.
6. Add a text property named Owner if it does not exist.
7. Add a date property named PublishDate if it does not exist.
8. Keep capitalization exactly as shown above.

Step 3: share the database with the integration

1. Open the Notion database page.
2. Click Share or the three-dot menu, depending on your Notion layout.
3. Find Connections.
4. Search for the integration you created.
5. Select the integration.
6. Confirm access.
7. If Notion asks whether to grant page access, approve it.

Step 4: copy the database ID

1. Open the database as a full page, not an inline view inside another page.
2. Copy the browser URL.
3. Find the long database ID in the URL. It is the long string after the workspace or page name and before any question mark.
4. You can paste the ID with or without hyphens.
5. Do not copy the view ID after ?v= as the database ID.

Step 5: save in PageOptimized

1. Return to PageOptimized.
2. Paste the integration secret into Integration token.
3. Paste the database ID into Database ID.
4. Leave Require approval on if Xavier should ask before syncing.
5. Click Save Notion.
6. Wait for the live credential check.
7. Click Create test page.
8. Open Notion and confirm the test page appears in the database.

Troubleshooting

1. If Notion says object_not_found, the database has not been shared with the integration or the database ID is wrong.
2. If the test page fails because of a property name, check Name, Keyword, Status, Owner, and PublishDate exactly.
3. If the token is rejected, create a fresh internal integration secret and paste it again.
4. If you shared a linked database, share the original source database instead.
5. Check the Audit Logs tab in PageOptimized for the exact Notion API response.