Automate Notion CRM workflows by creating Contact pages with POST /v1/pages (including relation properties linking to Company and Deal pages), updating deal stages with PATCH /v1/pages/{id}, and querying pipeline data with POST /v1/data_sources/{id}/query. Key challenge: each property type (relation, select, number, people) has a completely different write payload shape. Rate limit: 3 req/s — creating a contact + checking duplicates + linking relations = 4-5 sequential requests per lead.
API Quick Reference
Bearer Token
3 requests/second
JSON
Available
Understanding the Notion API
The Notion API uses a multi-source database model (as of version 2025-09-03) that maps well to CRM architecture: Contacts, Companies, and Deals can be modeled as separate data sources within a shared database container, linked via Notion's relation property type. Each data source has its own ID for querying, while the container database ID holds the schema.
CRM automation focuses on three operations: creating new pages (leads, contacts, deals), updating properties on existing pages (stage changes, assigned values), and querying for duplicates before creating (to prevent double-entry). The critical challenge is property type variety — Notion has 25+ property types and each has a completely different write payload structure.
File attachments (contracts, proposals) expire after approximately one hour — never cache file URLs, always re-fetch them on access. Official documentation: developers.notion.com.
https://api.notion.comSetting Up Notion API Authentication
Internal integrations use long-lived Bearer tokens. For CRM automation you need all three content capabilities: Read (to check duplicates), Insert (to create contacts and deals), and Update (to change deal stages). Share all CRM databases with the integration — Notion returns 404 for databases not explicitly shared, even if the integration token is valid.
- 1Go to notion.so/my-integrations (workspace owner required)
- 2Create or open your integration and enable: Read content, Insert content, Update content
- 3Copy the Internal Integration Secret (ntn_ prefix)
- 4Share your Contacts database with the integration via '...' > Connections
- 5Share your Companies database with the integration
- 6Share your Deals database with the integration
- 7Set environment variables: NOTION_TOKEN, NOTION_CONTACTS_DB_ID, NOTION_COMPANIES_DB_ID, NOTION_DEALS_DB_ID
1import os2import requests34NOTION_TOKEN = os.environ['NOTION_TOKEN']56HEADERS = {7 'Authorization': f'Bearer {NOTION_TOKEN}',8 'Notion-Version': '2025-09-03',9 'Content-Type': 'application/json'10}1112def get_data_source_id(database_id: str) -> str:13 """Fetch the data_source_id for a database container."""14 resp = requests.get(f'https://api.notion.com/v1/databases/{database_id}', headers=HEADERS)15 resp.raise_for_status()16 return resp.json()['data_sources'][0]['id']Security notes
- •Store all database IDs and the integration token in environment variables
- •CRM data is sensitive — only share the specific databases the integration needs
- •File URLs in Notion expire after ~1 hour — never cache them; always re-fetch on demand
- •Rotate the integration token immediately if exposed in logs or version control
- •Use Read-only mode during testing to avoid accidentally writing duplicate data
Key endpoints
/v1/pagesCreate a new page in a database — used to create Contact, Company, and Deal records. Relation properties link records across databases. Each property type has a different payload structure.
| Parameter | Type | Required | Description |
|---|---|---|---|
parent | object | required | {database_id: 'DB_ID'} to create a database row, or {page_id: 'PAGE_ID'} for a sub-page. |
properties | object | required | Map of property names to property values. Each property type has a unique shape — see Critical Gotchas. |
Request
1{"parent":{"database_id":"CONTACTS_DB_ID"},"properties":{"Name":{"title":[{"type":"text","text":{"content":"Jane Doe"}}]},"Email":{"email":"jane@acme.com"},"Company":{"relation":[{"id":"COMPANY_PAGE_ID"}]},"Status":{"select":{"name":"New Lead"}},"Deal Value":{"number":5000}}}Response
1{"object":"page","id":"new-contact-id","url":"https://notion.so/workspace/new-contact-id","properties":{"Name":{"title":[{"plain_text":"Jane Doe"}]},"Status":{"select":{"name":"New Lead"}}}}/v1/pages/{page_id}Update properties of an existing page — used to change deal stages, update contact status, or modify any CRM field. Partial updates: only include properties you want to change.
| Parameter | Type | Required | Description |
|---|---|---|---|
properties | object | optional | Partial update — include only the properties to change. Other properties remain unchanged. |
archived | boolean | optional | Set true to move to trash. In API version 2026-03-11 this becomes 'in_trash'. |
Request
1{"properties":{"Deal Stage":{"select":{"name":"Proposal Sent"}},"Close Date":{"date":{"start":"2026-06-30"}}}}Response
1{"object":"page","id":"deal-id","properties":{"Deal Stage":{"select":{"name":"Proposal Sent"}},"Close Date":{"date":{"start":"2026-06-30"}}}}/v1/data_sources/{data_source_id}/queryQuery a database for duplicate-checking before creating new contacts or for fetching pipeline data. Use email filter for contact deduplication.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | object | optional | Property filter object. Email filters use {property: 'Email', email: {equals: 'email@example.com'}}. |
page_size | number | optional | Max 100. For duplicate checks, set to 1. |
Request
1{"filter":{"property":"Email","email":{"equals":"jane@acme.com"}}}Response
1{"object":"list","results":[{"id":"existing-contact-id","properties":{"Name":{"title":[{"plain_text":"Jane Doe"}]},"Email":{"email":"jane@acme.com"}}}],"has_more":false}/v1/databases/{database_id}Fetch database schema to discover property names, types, and select/status option names. Essential before writing any CRM automation to get the exact option strings.
| Parameter | Type | Required | Description |
|---|---|---|---|
database_id | string | required | UUID of the Notion database container. |
Response
1{"object":"database","id":"db-id","properties":{"Deal Stage":{"type":"select","select":{"options":[{"name":"New Lead"},{"name":"Qualified"},{"name":"Proposal Sent"},{"name":"Closed Won"},{"name":"Closed Lost"}]}},"Deal Value":{"type":"number"}},"data_sources":[{"id":"ds-id"}]}Step-by-step automation
Check for Duplicate Contact by Email
Why: CRM data integrity depends on not creating duplicate contacts — a duplicate check before every create prevents garbage data.
Before creating a new contact, query the Contacts data source with an email filter. If results exist, return the existing contact ID instead of creating a new one. Set page_size to 1 — you only need to know if any match exists.
1curl -X POST 'https://api.notion.com/v1/data_sources/CONTACTS_DATA_SOURCE_ID/query' \2 -H 'Authorization: Bearer $NOTION_TOKEN' \3 -H 'Notion-Version: 2025-09-03' \4 -H 'Content-Type: application/json' \5 -d '{"filter":{"property":"Email","email":{"equals":"jane@acme.com"}},"page_size":1}'Pro tip: Email filter only works if the property type is 'email' (not 'rich_text'). If email is stored as a rich_text property, use {property: 'Email', rich_text: {equals: email}} instead.
Expected result: Either a page ID of the existing contact (skip creation, return the ID) or null (proceed to create).
Create a Contact Page with Properties
Why: Each Notion property type has a different write payload — getting this right is the core skill for any Notion CRM automation.
Send POST /v1/pages with parent.database_id set to the Contacts database. Include properties for name (title type), email (email type), phone (phone_number type), and company relation. The relation property links to an existing Company page by its ID — you must have the Company page ID before creating the Contact.
1curl -X POST 'https://api.notion.com/v1/pages' \2 -H 'Authorization: Bearer $NOTION_TOKEN' \3 -H 'Notion-Version: 2025-09-03' \4 -H 'Content-Type: application/json' \5 -d '{6 "parent": {"database_id": "CONTACTS_DB_ID"},7 "properties": {8 "Name": {"title": [{"type": "text", "text": {"content": "Jane Doe"}}]},9 "Email": {"email": "jane@acme.com"},10 "Phone": {"phone_number": "+1-555-0100"},11 "Company": {"relation": [{"id": "COMPANY_PAGE_ID"}]},12 "Lead Status": {"select": {"name": "New Lead"}}13 }14 }'Pro tip: If you get a 400 validation_error on a property, it almost always means either the property name does not match exactly (case-sensitive) or the property value shape is wrong for the property type. Fetch the database schema first and verify each property name and type.
Expected result: A new page object with the contact ID and all properties populated. The relation property linking to the Company page is immediately queryable.
Create a Deal and Link to Contact
Why: Deals are the revenue-tracking record in the CRM — creating them automatically from lead forms closes the pipeline gap between lead capture and pipeline tracking.
After creating the contact, create a Deal page in the Deals database with a relation linking back to the contact. Set the initial deal stage via a select property and add a deal value number. The relation property must reference the contact page ID returned in the previous step.
1curl -X POST 'https://api.notion.com/v1/pages' \2 -H 'Authorization: Bearer $NOTION_TOKEN' \3 -H 'Notion-Version: 2025-09-03' \4 -H 'Content-Type: application/json' \5 -d '{6 "parent": {"database_id": "DEALS_DB_ID"},7 "properties": {8 "Deal Name": {"title": [{"type": "text", "text": {"content": "Acme Corp - Enterprise"}}]},9 "Contact": {"relation": [{"id": "CONTACT_PAGE_ID"}]},10 "Deal Stage": {"select": {"name": "New Lead"}},11 "Deal Value": {"number": 12000},12 "Close Date": {"date": {"start": "2026-06-30"}}13 }14 }'Pro tip: Notion relations are directional by default. If your Deals database has a two-way sync configured with Contacts, the contact page will automatically show the linked deal. If it is a one-way relation, you may need to separately update the Contact's 'Deals' relation property.
Expected result: A new Deal page linked to the Contact page. In Notion, the relation appears as a connected record and the rollup properties (if configured) reflect the new deal value.
Update Deal Stage
Why: Moving deals through stages is the primary ongoing CRM operation — automating stage changes from external triggers (payment received, contract signed) keeps the pipeline accurate.
Send PATCH /v1/pages/{deal_id} with the updated select property for the deal stage. You can update multiple properties in a single PATCH — update stage, close date, and deal value simultaneously.
1curl -X PATCH 'https://api.notion.com/v1/pages/DEAL_PAGE_ID' \2 -H 'Authorization: Bearer $NOTION_TOKEN' \3 -H 'Notion-Version: 2025-09-03' \4 -H 'Content-Type: application/json' \5 -d '{"properties": {"Deal Stage": {"select": {"name": "Closed Won"}}}}'Pro tip: Select option names are case-sensitive and must exactly match an existing option in the database. If the option does not exist, Notion returns a 400 validation_error. Use GET /v1/databases/{id} to fetch the current option list before sending updates.
Expected result: The deal page in Notion reflects the new stage. Any rollup properties in the Contacts or Companies database that aggregate deal stages update automatically.
Complete working code
This complete script processes an incoming webhook lead (name, email, phone, company name, deal value) by checking for duplicate contacts, creating or reusing a contact, creating a linked deal, and returning the created record IDs. Includes rate limit handling with 350ms delays.
1import os2import time3import requests45NOTION_TOKEN = os.environ['NOTION_TOKEN']6CONTACTS_DB_ID = os.environ['NOTION_CONTACTS_DB_ID']7CONTACTS_DS_ID = os.environ['NOTION_CONTACTS_DS_ID']8COMPANIES_DS_ID = os.environ['NOTION_COMPANIES_DS_ID']9DEALS_DB_ID = os.environ['NOTION_DEALS_DB_ID']1011H = {12 'Authorization': f'Bearer {NOTION_TOKEN}',13 'Notion-Version': '2025-09-03',14 'Content-Type': 'application/json'15}1617def api(method, path, **kwargs):18 resp = getattr(requests, method)(f'https://api.notion.com{path}', headers=H, **kwargs)19 if resp.status_code == 429:20 time.sleep(int(resp.headers.get('Retry-After', 5)))21 return api(method, path, **kwargs)22 resp.raise_for_status()23 time.sleep(0.35)24 return resp.json()2526def find_by_email(ds_id, email):27 r = api('post', f'/v1/data_sources/{ds_id}/query',28 json={'filter': {'property': 'Email', 'email': {'equals': email}}, 'page_size': 1})29 return r['results'][0]['id'] if r['results'] else None3031def find_company_by_name(name):32 r = api('post', f'/v1/data_sources/{COMPANIES_DS_ID}/query',33 json={'filter': {'property': 'Name', 'title': {'equals': name}}, 'page_size': 1})34 return r['results'][0]['id'] if r['results'] else None3536def create_page(db_id, props):37 return api('post', '/v1/pages', json={'parent': {'database_id': db_id}, 'properties': props})3839def process_lead(lead: dict) -> dict:40 print(f"Processing lead: {lead['email']}")41 # Check duplicate42 contact_id = find_by_email(CONTACTS_DS_ID, lead['email'])43 if contact_id:44 print(f' Existing contact: {contact_id}')45 else:46 # Find or skip company47 company_id = find_company_by_name(lead.get('company', ''))48 props = {49 'Name': {'title': [{'type': 'text', 'text': {'content': lead['name']}}]},50 'Email': {'email': lead['email']},51 'Lead Status': {'select': {'name': 'New Lead'}}52 }53 if lead.get('phone'):54 props['Phone'] = {'phone_number': lead['phone']}55 if company_id:56 props['Company'] = {'relation': [{'id': company_id}]}57 contact = create_page(CONTACTS_DB_ID, props)58 contact_id = contact['id']59 print(f' Created contact: {contact_id}')60 # Create deal61 deal = create_page(DEALS_DB_ID, {62 'Deal Name': {'title': [{'type': 'text', 'text': {'content': f"{lead.get('company', 'Unknown')} - {lead.get('product', 'Deal')}"}}]},63 'Contact': {'relation': [{'id': contact_id}]},64 'Deal Stage': {'select': {'name': 'New Lead'}},65 'Deal Value': {'number': lead.get('deal_value', 0)}66 })67 print(f' Created deal: {deal["id"]}')68 return {'contact_id': contact_id, 'deal_id': deal['id']}6970if __name__ == '__main__':71 result = process_lead({72 'name': 'Jane Doe',73 'email': 'jane@acme.com',74 'phone': '+1-555-0100',75 'company': 'Acme Corp',76 'product': 'Enterprise Plan',77 'deal_value': 1200078 })79 print('Result:', result)Error handling
{"object":"error","status":400,"code":"validation_error","message":"body.properties.Company.relation is invalid"}The relation property value is malformed. Relation must be an array of objects: [{id: 'page-uuid'}], not a string or single object.
Use {"relation": [{"id": "PAGE_UUID"}]}. The array is required even for a single relation. Verify the linked page ID exists and is in the correct database.
No retry — fix the property value shape.
{"object":"error","status":400,"code":"validation_error","message":"Invalid option \"New Lead\" for select property."}The select option name does not match an existing option in the database. Select option names are case-sensitive.
Fetch the database schema with GET /v1/databases/{id} and check properties.['Deal Stage'].select.options for the exact option names. If 'New Lead' does not exist, create it in Notion first.
No retry — fix the option name.
{"object":"error","status":404,"code":"object_not_found","message":"Could not find database with ID: ..."}The database is not shared with the integration. Notion returns 404 (not 403) for resources not connected.
Open each CRM database in Notion, click '...' > Connections, and connect the integration. Verify the database IDs from the URL.
No retry — share the databases first.
{"object":"error","status":400,"code":"missing_version"}The Notion-Version header was omitted.
Add Notion-Version: 2025-09-03 to all request headers. Define once in a shared constants object.
No retry — fix the header.
{"object":"error","status":429,"code":"rate_limited"}Creating one lead with duplicate check + contact create + deal create = 4 requests. Processing multiple leads simultaneously hits the 3 req/s limit quickly.
Add 350ms delays between all API calls. Process leads sequentially, not in parallel. Honor the Retry-After header value.
Sleep for Retry-After seconds, then retry with exponential backoff up to 64s.
Rate Limits for Notion API
| Scope | Limit | Window |
|---|---|---|
| Per integration token | 3 requests average | per second |
| Requests per new lead | 4-5 sequential requests | per lead (duplicate check + contact + company lookup + deal create) |
1import time2import requests34def notion_api(method, url, headers, **kwargs):5 for i in range(5):6 r = getattr(requests, method)(url, headers=headers, **kwargs)7 if r.status_code == 429:8 wait = int(r.headers.get('Retry-After', 2 ** i))9 print(f'Rate limited, waiting {wait}s')10 time.sleep(wait)11 continue12 r.raise_for_status()13 time.sleep(0.35) # proactive rate limit buffer14 return r.json()15 raise Exception('Max retries hit')- Add 350ms delays after every API call — proactive throttling prevents 429 errors entirely for low-volume workflows
- Process leads sequentially rather than in parallel when the volume is under 500/day
- Cache company pages to avoid repeated lookups for the same company — a company rarely changes
- Use page_size: 1 for duplicate checks — you only need to know if any match exists
- Batch deal updates during off-hours when interactive Notion usage is lower
Security checklist
- Store all Notion IDs and the integration token in environment variables
- Only share the specific CRM databases with the integration — not unrelated workspaces
- CRM data includes PII (emails, phone numbers) — comply with GDPR/CCPA storage requirements
- File attachment URLs in Notion expire after ~1 hour — never persist them; always re-fetch from the API
- Validate and sanitize all incoming lead data before writing to Notion to prevent injection via property values
- Rotate the integration token quarterly or immediately upon exposure
- Log CRM write operations with timestamps for audit trail — store logs outside Notion
Automation use cases
Form-to-CRM Lead Capture
intermediateReceive a webhook from Typeform, Tally, or HubSpot Forms and automatically create Notion contact and deal records with deduplication.
Pipeline Value Calculator
intermediateRun a daily query against the Deals database, sum deal values by stage, and post a pipeline summary to Slack with MRR and weighted pipeline calculations.
Stripe Payment to CRM Stage Update
advancedReceive a Stripe payment_intent.succeeded webhook and automatically update the linked Notion deal stage to 'Closed Won' and set the close date to today.
No-code alternatives
Don't want to write code? These platforms can automate the same workflows visually.
Zapier
Free tier available; paid plans from $19.99/monthZapier can create Notion database rows from form submissions and update properties, making basic CRM entry automation accessible without code.
- + No code required
- + Connects to 5,000+ form and CRM tools
- + Built-in duplicate checking with Search step
- - Limited relation property support
- - Cannot create linked pages in multiple databases in a single Zap without multi-step plans
- - Cost scales with lead volume
Make
Free tier available; paid plans from $9/monthMake's Notion module supports creating pages and updating properties with stronger multi-step flow control than Zapier for complex CRM pipelines.
- + Better multi-step support for contact + deal creation flow
- + Router module for conditional deal stages
- + More affordable at high volume
- - More complex to set up than Zapier
- - Relation property linking requires careful mapping
- - Notion module may lag API updates
n8n
Free self-hosted; cloud from €20/monthn8n's Notion node supports full page creation with all property types and code nodes allow custom deduplication logic before writing to Notion.
- + Self-hostable
- + Code node handles deduplication and business logic
- + No per-operation pricing
- - Requires server infrastructure
- - More setup time
- - Notion API version support may lag
Best practices
- Always deduplicate by email before creating contacts — run a POST /v1/data_sources/{id}/query with email filter first
- Fetch the database schema once at startup to cache property names and select option names
- Write a property type reference comment in your code listing all Notion property shapes — it will save hours of debugging
- Relation properties always require an array even for a single ID: {relation: [{id: 'PAGE_ID'}]}
- File attachment URLs expire after ~1 hour — never store them; always re-fetch from the API when needed
- Use PATCH /v1/pages/{id} for stage updates — it only updates the specified properties, leaving others unchanged
- Add 350ms delays between all API calls to stay well under the 3 req/s rate limit
Ask AI to help
Copy one of these prompts to get a personalized, working implementation.
I'm automating a Notion CRM with the Notion API v2025-09-03. When I try to create a contact page with a Company relation property, I get a 400 validation_error. My payload is: {paste properties object here}. The database schema shows the Company property type is 'relation'. What is the correct write shape for a relation property in POST /v1/pages?
Build a Next.js CRM dashboard that syncs with Notion. The app should: accept new lead submissions via a form (name, email, phone, company, deal value), call POST /api/leads which checks for duplicates using POST /v1/data_sources/{id}/query, creates a contact page in Notion via POST /v1/pages with relation to a company page, creates a linked deal page, and returns the created IDs. Also show a pipeline kanban board reading deals from Notion by stage using POST /v1/data_sources/{id}/query with stage filter, grouped by 'New Lead', 'Qualified', 'Proposal Sent', 'Closed Won', 'Closed Lost'. Use Notion-Version: 2025-09-03 headers. Store NOTION_TOKEN in env vars.
Frequently asked questions
Why does every property type have a different write format in Notion?
Notion's data model treats each property type as a distinct structured object rather than a generic key-value pair. This allows Notion to maintain type safety and render properties correctly in the UI. The trade-off is that you must know the exact structure for each type: title uses a rich text array, email uses a plain string, relation uses an array of ID objects, select uses a name object, number uses a plain number, date uses a start/end structure, and so on.
How do I link a Contact to a Company using a relation property?
The relation property write shape is {"relation": [{"id": "COMPANY_PAGE_ID"}]}. You must know the Company page ID before creating the Contact. To find it, query the Companies data source for a matching company name first. For two-way relations, Notion automatically updates both sides when you set one side.
Can I create a Contact and Deal in a single API call?
No. Creating the Contact and Deal requires two separate POST /v1/pages calls because the Deal needs to reference the Contact's page ID, which is only available after the Contact is created. The minimum sequence is: (1) check for duplicate contact, (2) create contact, (3) create deal with contact relation.
Why do Notion file attachment URLs expire?
Notion stores file attachments on AWS S3 with time-limited signed URLs (approximately 1 hour). After expiry, the URL returns 403 from S3. Always re-fetch the page or block containing the file URL when you need to access it — never cache file URLs between requests.
Is the Notion API free for CRM automations?
Yes. The Notion API has no paid tier — it is free regardless of your workspace plan. The only limitation is the 3 req/s rate limit, which applies to all plans equally.
How do I calculate pipeline value across all deals?
Query all deals using POST /v1/data_sources/{deals_ds_id}/query, paginate all results, then sum the 'Deal Value' number properties in your code grouped by 'Deal Stage' select values. There is no built-in aggregation endpoint — you must compute totals in your script.
What is the difference between data_source_id and database_id?
In Notion API v2025-09-03, a database is a container (GET /v1/databases/{database_id}) that holds one or more data sources. Row queries and page creation use the database_id for parent, but query operations use the data_source_id. Fetch GET /v1/databases/{database_id} and look at data_sources[0].id to get the data_source_id.
Can RapidDev build a custom Notion CRM integration?
Yes. RapidDev has built 600+ apps including CRM pipelines integrated with Notion, Stripe, and form tools. We can build a fully automated lead-to-deal pipeline with deduplication, multi-database linking, and external notifications. Visit rapidevelopers.com for a free consultation.
Need this automated?
Our team has built 600+ apps with API automations. We can build this for you.
Book a free consultation