# How to Automate Notion CRM Workflows using the API

- Tool: API Automations
- Difficulty: Intermediate
- Fix time: 30-60 minutes
- Compatibility: Free — internal Notion integration with Read content, Insert content, and Update content capabilities
- Last updated: May 2026

## TL;DR

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.

## 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

## 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.

---

Source: https://www.rapidevelopers.com/api-automations/how-to-automate-notion-crm-workflows-using-the-api
© RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-notion-crm-workflows-using-the-api