Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/notion-data-handling/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-data-handling. Copyright stays with the author (MIT).

Notion Data Handling

Overview

Handle sensitive data correctly when integrating with Notion: detect PII in page properties and text content, redact sensitive fields before logging or exporting, minimize data exposure with filter_properties, and implement GDPR/CCPA compliance patterns — right-of-access exports, right-of-deletion (archive or field clearing), and retention-based archival, all with audit logging.

The full, copy-ready TypeScript and Python implementations live in references/ so this file stays a navigable map. Read top-to-bottom for the workflow; drill into a reference file when you need the complete code for a step.

Prerequisites

@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Understanding of which Notion databases contain personal data
Audit logging infrastructure (structured logs, SIEM, or Notion audit database)
Legal guidance on applicable regulations (GDPR, CCPA, HIPAA, etc.)

Authentication

All examples authenticate with an internal integration token read from the environment — never hardcode it:

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Create the token at notion.so/my-integrations and share each target database with the integration. Deletion and retention flows additionally require the integration to hold Update capability, or pages.update returns 403.

Instructions

Work through three stages. Each links to a reference file with the complete implementation.

Step 1 — Detect PII

Notion pages carry PII in dedicated email/phone_number/people properties and embedded in free-text rich_text/title values. Scan both: check known-sensitive property types directly, and run regex matchers (email, phone, SSN, credit card, IP) over text. Loop the whole database through pagination until has_more is false. Skeleton:

function scanPageForPII(page: PageObjectResponse): PIIFinding[] {
  // check email / phone_number / people property types,
  // then run PII_PATTERNS regexes over rich_text + title text
}

Full TS + Python scanners: pii-detection.md.

Step 2 — Redact and minimize

Never log or export raw page objects. Pass every page through an allowlist-shaped redactor that masks sensitive property types and named fields while letting vetted scalar types pass through. Then cut exposure at the source with filter_properties, which returns only the properties you name:

notion.databases.query({ database_id: dbId, filter_properties: ['Status', 'Name'] });

Full redactPageProperties implementation and minimization guidance: redaction-minimization.md.

Step 3 — Serve GDPR/CCPA requests

Three data-subject workflows, each emitting a structured audit event you retain as proof:

Right of access (Article 15) — query every database for the user and export their pages, then audit-log the export.
Right of deletion (Article 17) — choose archive (soft-delete the whole page, recoverable ~30 days) or clear_pii (null the PII fields, keep the record). Throttle bulk updates to ~3 req/s.
Retention — archive pages whose last_edited_time is older than the retention window.

Full export, deletion, and retention functions: compliance-patterns.md.

Output

PII detection scanning all property types and text content (TS + Python)
Redaction layer preventing PII leakage in logs and exports
Data minimization via filter_properties in API queries
GDPR Article 15 data export with audit logging
GDPR Article 17 deletion (archive or field clearing) with rate limiting
Retention-based archival with structured compliance logging
Audit trail for all data access, export, and deletion events

Error Handling

Issue	Cause	Solution
PII in application logs	Missing redaction layer	Use `redactPageProperties` for all logging
Deletion fails on pages (403)	Integration lacks Update capability	Edit integration at notion.so/my-integrations
Export missing pages	Pagination not handled	Use `start_cursor` loop until `has_more` is false
Rate limit during bulk deletion	Too many update calls	Throttle to 3 requests/second with delays
Regex false positives	Overly broad patterns	Tune patterns for your data; consider allowlists
Regex misses on second page	Stateful `g`-flag `lastIndex`	Reset `pattern.lastIndex = 0` before each `.test()`
Audit log gaps	Async logging dropped events	Use synchronous logging for compliance events

Examples

A quick database PII audit and a compact Python export, composing the building blocks above:

const findings = await auditDatabaseForPII(process.env.NOTION_DB_ID!);
console.log(`PII audit: ${findings.length} pages with PII detected`);

Both full examples (TS audit summary + Python Article 15 export): examples.md.

Resources

pii-detection.md — full TS + Python PII scanners
redaction-minimization.md — redactor + filter_properties
compliance-patterns.md — export, deletion, retention
examples.md — end-to-end snippets
Notion Page Properties Reference — all property types
Database Query with filter_properties — data minimization
Notion API Update Page — archive and property updates
CCPA Overview — California Consumer Privacy Act requirements
For enterprise access control and multi-workspace permissions, see notion-enterprise-rbac.

notion-data-handling

About