Core Forms
Get Core Forms

Notion Integration

Create a new page in a Notion database for each form submission.

Action type: notion Class: Core_Forms\Actions\Notion Source: src/actions/class-notion.php

Setup

1. Create a Notion Integration

  1. Go to notion.so/my-integrations.
  2. Click New integration, give it a name, and select the workspace.
  3. Copy the Integration Token (starts with secret_...).

2. Share the Database

  1. Open the Notion database you want to receive submissions.
  2. Click Share (or the ... menu) and invite your integration.
  3. Copy the Database ID from the URL: https://notion.so/{workspace}/{DATABASE_ID}?v=... (the 32-character hex string).

3. Configure in Core Forms

  1. Edit your form > Actions tab > Add Action > Add to Notion.
  2. Paste the Integration Token and Database ID.
  3. Optionally configure field mapping.

Settings Reference

Setting Required Default Description
Integration Token Yes -- Notion internal integration token (secret_...)
Database ID Yes -- 32-character ID from the database URL
Field Mapping No Auto-map Maps form fields to Notion database properties

Field Mapping Format

One mapping per line, form_field=Notion Property:

name=Name
email=Email
message=Message
company=Company

When left empty, form fields are auto-mapped using the field name with underscores replaced by spaces and the first letter capitalized (e.g., first_name becomes First name).

How Properties Are Created

  • The Name property (title type, required by Notion) is always set to {Form Title} -- {timestamp}.
  • All other properties are created as rich_text type.
  • Values are truncated to 2,000 characters (Notion API limit for rich text).
  • Array values (checkboxes, multi-select) are joined with commas.

Example

Form with name, email, phone, and message fields, mapped as:

name=Contact Name
email=Email Address
message=Inquiry

Creates a Notion page with: - Name (title): "Contact Form -- 2026-04-09 10:30:00" - Contact Name (rich_text): "Jane Smith" - Email Address (rich_text): "jane@example.com" - Inquiry (rich_text): "I'd like to learn more." - Phone (rich_text, auto-mapped): "555-0100"

How It Works

  1. Parses the field mapping configuration.
  2. Builds Notion API properties with the title property set to form title + timestamp.
  3. POSTs to https://api.notion.com/v1/pages with the database parent and properties.
  4. Uses Notion API version 2022-06-28.
  5. The request times out after 20 seconds.
  6. Returns true if the response status is below 400.

Troubleshooting

  • "Could not find database": Ensure the database is shared with the integration. Click Share on the database page and add the integration.
  • Property type mismatch: All fields are sent as rich_text. If your Notion database has properties with other types (number, select, date), the API may reject them. Adjust your database property types to accept rich text.
  • Token format: The token must start with secret_. Internal integrations only -- OAuth tokens are not supported.