A Notion database is a handy place for form submissions. Each one becomes a page you can open, add notes to, give a status and assign, and the whole team sees it in a board or table view.

Notion's own forms do this, but they live on a Notion page. If the form is already on your site, in plain HTML or React or Astro, something has to take the post and call Notion's API. This guide does it two ways: a small Cloudflare Worker you run yourself, and a form backend that maps the properties for you.

Why the browser can't call Notion directly

Notion's API uses an integration secret. Anything in your page's JavaScript is public, so a secret in the browser lets anyone add pages to your database, and read it too. Notion's API also doesn't answer browser requests from other sites (no CORS headers), so the call fails there anyway.

So the form posts to a small server of yours, and only that server holds the secret.

Option A: a Cloudflare Worker

Set up the database

Create a database with a Name property (the title, every database has one), an Email property of type Email and a Message property of type Text. Then create the integration:

  1. Open notion.so/profile/integrations and create an internal integration
  2. Under Capabilities, turn on Insert content
  3. Copy the Internal Integration Secret
  4. Open the database in Notion, click ⋯ → Connections and add the integration

Don't skip step 4: an integration sees nothing until a page or database is shared with it. You also need the database ID: open the database as a full page and it's the 32 characters before the ?v= in the URL.

The Worker

// Form field name → [Notion property name, property type] const PROPERTIES = { name: ["Name", "title"], email: ["Email", "email"], message: ["Message", "rich_text"], }; const ALLOWED_ORIGIN = "https://example.com"; export default { async fetch(request, env) { const headers = { "Access-Control-Allow-Origin": ALLOWED_ORIGIN }; if (request.method !== "POST") return new Response("Method not allowed", { status: 405 }); const form = await request.formData(); // Honeypot filled in: answer OK so the bot learns nothing. if (form.get("_gotcha")) return Response.json({ ok: true }, { headers }); const properties = {}; for (const [field, [property, type]] of Object.entries(PROPERTIES)) { // A single Notion text item holds 2,000 characters. const value = String(form.get(field) ?? "").trim().slice(0, 2000); if (!value) continue; if (type === "email") properties[property] = { email: value }; else properties[property] = { [type]: [{ type: "text", text: { content: value } }] }; } if (!properties.Email) return Response.json({ ok: false }, { status: 400, headers }); const res = await fetch("https://api.notion.com/v1/pages", { method: "POST", headers: { Authorization: `Bearer ${env.NOTION_TOKEN}`, "Notion-Version": "2022-06-28", "Content-Type": "application/json", }, body: JSON.stringify({ parent: { database_id: env.NOTION_DATABASE_ID }, properties, }), }); if (!res.ok) { console.error("Notion error", res.status, await res.text()); return Response.json({ ok: false }, { status: 502, headers }); } return Response.json({ ok: true }, { headers }); }, }; 

Change ALLOWED_ORIGIN to your site. Then deploy it and store the secret, so it never sits in your code:

npx wrangler deploy npx wrangler secret put NOTION_TOKEN 

Add NOTION_DATABASE_ID as a variable in wrangler.jsonc or the dashboard.

The title property has to be written as title and text as rich_text. Each property type has its own shape, which is why the Worker keeps the type next to the name.

The Worker pins Notion API version 2022-06-28, which takes a database ID as the parent. Newer versions add pages to a data source inside the database instead, so you'd look up the data source ID first. The older version is simpler and works for a database with one data source, which is what a new database has.

The form

The Worker answers with JSON, so post with fetch() and show the thank-you message on your own page. A FormData body doesn't need a CORS preflight, which keeps the Worker short.

<form id="contact"> <input name="name" placeholder="Name" required> <input name="email" type="email" placeholder="Email" required> <textarea name="message" placeholder="Message" required></textarea> <!-- Honeypot: hidden from people, bots fill it in --> <div aria-hidden="true" style="position:absolute; left:-9999px"> <input type="text" name="_gotcha" tabindex="-1" autocomplete="off"> </div> <button type="submit">Send</button> </form> <script> const form = document.getElementById("contact"); form.addEventListener("submit", async (event) => { event.preventDefault(); const res = await fetch("https://your-worker.your-subdomain.workers.dev", { method: "POST", body: new FormData(form), }); form.replaceWith(res.ok ? "Thanks, we got your message." : "Something went wrong. Please try again."); }); </script> 

Submit it once and a page should show up in the database.

Where it breaks

  • Property names and types have to match. Rename Email in Notion, or change it to a Text property, and every submission fails with a validation_error until you change the Worker.
  • Not shared. If the integration isn't added under the database's Connections, or Insert content is off, Notion answers 404 or 403 and nothing saves.
  • Long messages. One text item holds 2,000 characters. The Worker cuts there. To keep more, you split the text into several items yourself.
  • Select and status. A select value that isn't an option yet is added as a new one. A status value has to exist already, or the whole page is refused.
  • Rate limits. Notion allows about 3 requests a second on average and answers 429 above that. The Worker doesn't retry, so a burst loses submissions.
  • No second copy. When Notion is down or refuses a page, the Worker logs an error and the submission is gone. Fixing that means a queue and retries.
  • Spam. The honeypot only stops simple bots. Written sales pitches get through and become pages in your database.

For a personal site with a few messages a week, the Worker is fine. Past that, most of the work is in the list above.

Option B: a form backend that maps the properties

With Formkove, the form posts to a Formkove URL. Each submission is saved, checked for spam, emailed to you and added to Notion as a page.

Point the form at Formkove. Create a form at app.formkove.com and use its endpoint as the action. No server and no script, and the _gotcha honeypot is on by default.

<form action="https://app.formkove.com/api/forms/YOUR_FORM_ID/submissions" method="POST"> 

Connect Notion. Create the internal integration and share the database with it, as in the steps above. Then, in the form's Integrations, click Connect Notion, paste the secret and pick the database. The secret is stored encrypted and never shown again.

Map the properties. Formkove lists the database's properties. For each one you pick a form field, a Formkove value (Submitted at, Submission ID, Form name, Sentiment, Tags, Spam score, File links) or a fixed text like Website. Properties with the same name as a form field are filled in for you. It writes title, text, number, checkbox, select, multi-select, status, date, email, phone and URL properties and converts each value to the property's type. Rename or add a property in Notion and you fix it with Edit mapping, without touching code. Click Send test to add a sample page.

Send only some submissions. Describe your tags in plain words on the form's AI & Spam page (for example, sales-lead: wants a quote, a price or to hire us), then add a routing rule to the Notion connection:

  • Tag has any of sales-lead

Now the database only gets leads, and you can map Sentiment and Tags to their own properties. Rules can also test any form field, like budget is greater than 5000. Email isn't routed: you still get every real submission by email.

What comes with it:

  • Spam held back before anything reaches Notion, so your database stays clean. It's kept in your dashboard for 30 days in case one was a real message.
  • Every submission saved, even when Notion is down or refuses a page. Failed deliveries are retried and listed in Delivery history with the reason.
  • Select and status handled. If Notion refuses a value, Formkove saves the page without its select and status properties instead of losing it, and the delivery history says so.
  • Long messages kept. Text goes in whole, up to 50,000 characters, split into Notion's 2,000-character items for you.
  • Rate limits on every form: 10 a minute and 30 an hour per IP address.

Notion, tags and routing are on the Pro and Agency plans, and Free accounts get them on their first 50 submissions (pricing). Setup details are in the Notion docs.

Originally published on formkove.com.