1# Notion Property Types Reference
2 
3This document covers database property schemas and page property values in the Notion API.
4 
5## Property Schema Objects (Database Columns)
6 
7Property schemas define the structure of database columns. Every database requires exactly one `title` property.
8 
9### Title
10 
11```json
12{
13  "Name": {
14    "id": "title",
15    "type": "title",
16    "title": {}
17  }
18}
19```
20 
21Required. One per database. Controls the title displayed at the top of pages.
22 
23### Rich Text
24 
25```json
26{
27  "Description": {
28    "type": "rich_text",
29    "rich_text": {}
30  }
31}
32```
33 
34### Number
35 
36```json
37{
38  "Price": {
39    "type": "number",
40    "number": {
41      "format": "dollar"
42    }
43  }
44}
45```
46 
47Format options:
48- Numbers: `number`, `number_with_commas`, `percent`
49- Currencies: `dollar`, `euro`, `pound`, `yen`, `ruble`, `rupee`, `won`, `yuan`, `real`, `lira`, `canadian_dollar`, `australian_dollar`, `singapore_dollar`, `hong_kong_dollar`, `new_zealand_dollar`, `krona`, `norwegian_krone`, `mexican_peso`, `rand`, `new_taiwan_dollar`, `danish_krone`, `zloty`, `baht`, `forint`, `koruna`, `shekel`, `chilean_peso`, `philippine_peso`, `dirham`, `colombian_peso`, `riyal`, `ringgit`, `leu`, `argentine_peso`, `uruguayan_peso`, `peruvian_sol`
50 
51### Select
52 
53```json
54{
55  "Status": {
56    "type": "select",
57    "select": {
58      "options": [
59        {"id": "uuid", "name": "To Do", "color": "red"},
60        {"id": "uuid", "name": "In Progress", "color": "yellow"},
61        {"id": "uuid", "name": "Done", "color": "green"}
62      ]
63    }
64  }
65}
66```
67 
68Color options: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`
69 
70### Multi-Select
71 
72```json
73{
74  "Tags": {
75    "type": "multi_select",
76    "multi_select": {
77      "options": [
78        {"id": "uuid", "name": "Tag1", "color": "blue"},
79        {"id": "uuid", "name": "Tag2", "color": "green"}
80      ]
81    }
82  }
83}
84```
85 
86Maximum 100 options.
87 
88### Status
89 
90```json
91{
92  "Project Status": {
93    "type": "status",
94    "status": {
95      "options": [
96        {"id": "uuid", "name": "Not started", "color": "default"},
97        {"id": "uuid", "name": "In progress", "color": "blue"},
98        {"id": "uuid", "name": "Done", "color": "green"}
99      ],
100      "groups": [
101        {"id": "uuid", "name": "To-do", "color": "gray", "option_ids": ["..."]},
102        {"id": "uuid", "name": "In progress", "color": "blue", "option_ids": ["..."]},
103        {"id": "uuid", "name": "Complete", "color": "green", "option_ids": ["..."]}
104      ]
105    }
106  }
107}
108```
109 
110**Note**: Creating new status properties via API is not supported.
111 
112### Date
113 
114```json
115{
116  "Due Date": {
117    "type": "date",
118    "date": {}
119  }
120}
121```
122 
123### Checkbox
124 
125```json
126{
127  "Complete": {
128    "type": "checkbox",
129    "checkbox": {}
130  }
131}
132```
133 
134### URL
135 
136```json
137{
138  "Website": {
139    "type": "url",
140    "url": {}
141  }
142}
143```
144 
145### Email
146 
147```json
148{
149  "Contact": {
150    "type": "email",
151    "email": {}
152  }
153}
154```
155 
156### Phone Number
157 
158```json
159{
160  "Phone": {
161    "type": "phone_number",
162    "phone_number": {}
163  }
164}
165```
166 
167### People
168 
169```json
170{
171  "Assignee": {
172    "type": "people",
173    "people": {}
174  }
175}
176```
177 
178### Files
179 
180```json
181{
182  "Attachments": {
183    "type": "files",
184    "files": {}
185  }
186}
187```
188 
189### Relation
190 
191Single-direction relation:
192 
193```json
194{
195  "Related Tasks": {
196    "type": "relation",
197    "relation": {
198      "database_id": "target-database-uuid",
199      "type": "single_property"
200    }
201  }
202}
203```
204 
205Dual-direction relation:
206 
207```json
208{
209  "Related Tasks": {
210    "type": "relation",
211    "relation": {
212      "database_id": "target-database-uuid",
213      "type": "dual_property",
214      "dual_property": {
215        "synced_property_name": "Related Projects",
216        "synced_property_id": "..."
217      }
218    }
219  }
220}
221```
222 
223### Rollup
224 
225```json
226{
227  "Total Hours": {
228    "type": "rollup",
229    "rollup": {
230      "relation_property_name": "Tasks",
231      "relation_property_id": "...",
232      "rollup_property_name": "Hours",
233      "rollup_property_id": "...",
234      "function": "sum"
235    }
236  }
237}
238```
239 
240Rollup functions:
241- Aggregation: `count_all`, `count_values`, `count_unique_values`, `count_empty`, `count_not_empty`, `percent_empty`, `percent_not_empty`
242- Numbers: `sum`, `average`, `median`, `min`, `max`, `range`
243- Dates: `earliest_date`, `latest_date`, `date_range`
244- Booleans: `checked`, `unchecked`, `percent_checked`, `percent_unchecked`
245- Display: `show_original`, `show_unique`
246 
247### Formula
248 
249```json
250{
251  "Full Name": {
252    "type": "formula",
253    "formula": {
254      "expression": "prop(\"First Name\") + \" \" + prop(\"Last Name\")"
255    }
256  }
257}
258```
259 
260### Created Time (Read-Only)
261 
262```json
263{
264  "Created": {
265    "type": "created_time",
266    "created_time": {}
267  }
268}
269```
270 
271### Created By (Read-Only)
272 
273```json
274{
275  "Creator": {
276    "type": "created_by",
277    "created_by": {}
278  }
279}
280```
281 
282### Last Edited Time (Read-Only)
283 
284```json
285{
286  "Updated": {
287    "type": "last_edited_time",
288    "last_edited_time": {}
289  }
290}
291```
292 
293### Last Edited By (Read-Only)
294 
295```json
296{
297  "Editor": {
298    "type": "last_edited_by",
299    "last_edited_by": {}
300  }
301}
302```
303 
304### Unique ID (Read-Only)
305 
306```json
307{
308  "ID": {
309    "type": "unique_id",
310    "unique_id": {
311      "prefix": "PROJ"
312    }
313  }
314}
315```
316 
317---
318 
319## Property Value Objects (Page Properties)
320 
321Property values are used when creating or updating pages.
322 
323### Title Value
324 
325```json
326{
327  "Name": {
328    "title": [
329      {"type": "text", "text": {"content": "Page Title"}}
330    ]
331  }
332}
333```
334 
335### Rich Text Value
336 
337```json
338{
339  "Description": {
340    "rich_text": [
341      {"type": "text", "text": {"content": "Description text"}}
342    ]
343  }
344}
345```
346 
347### Number Value
348 
349```json
350{
351  "Price": {
352    "number": 99.99
353  }
354}
355```
356 
357### Select Value
358 
359```json
360{
361  "Status": {
362    "select": {"name": "In Progress"}
363  }
364}
365```
366 
367Or by ID:
368 
369```json
370{
371  "Status": {
372    "select": {"id": "option-uuid"}
373  }
374}
375```
376 
377### Multi-Select Value
378 
379```json
380{
381  "Tags": {
382    "multi_select": [
383      {"name": "Tag1"},
384      {"name": "Tag2"}
385    ]
386  }
387}
388```
389 
390### Status Value
391 
392```json
393{
394  "Project Status": {
395    "status": {"name": "In progress"}
396  }
397}
398```
399 
400### Date Value
401 
402Single date:
403 
404```json
405{
406  "Due Date": {
407    "date": {
408      "start": "2024-12-31"
409    }
410  }
411}
412```
413 
414Date with time:
415 
416```json
417{
418  "Meeting": {
419    "date": {
420      "start": "2024-12-31T14:00:00.000Z",
421      "time_zone": "America/New_York"
422    }
423  }
424}
425```
426 
427Date range:
428 
429```json
430{
431  "Sprint": {
432    "date": {
433      "start": "2024-01-01",
434      "end": "2024-01-14"
435    }
436  }
437}
438```
439 
440### Checkbox Value
441 
442```json
443{
444  "Complete": {
445    "checkbox": true
446  }
447}
448```
449 
450### URL Value
451 
452```json
453{
454  "Website": {
455    "url": "https://example.com"
456  }
457}
458```
459 
460### Email Value
461 
462```json
463{
464  "Contact": {
465    "email": "[email protected]"
466  }
467}
468```
469 
470### Phone Number Value
471 
472```json
473{
474  "Phone": {
475    "phone_number": "+1-555-123-4567"
476  }
477}
478```
479 
480### People Value
481 
482```json
483{
484  "Assignee": {
485    "people": [
486      {"id": "user-uuid"}
487    ]
488  }
489}
490```
491 
492Maximum 100 users.
493 
494### Files Value
495 
496External files:
497 
498```json
499{
500  "Attachments": {
501    "files": [
502      {
503        "name": "Document.pdf",
504        "type": "external",
505        "external": {"url": "https://example.com/doc.pdf"}
506      }
507    ]
508  }
509}
510```
511 
512Uploaded files (use file upload API first):
513 
514```json
515{
516  "Attachments": {
517    "files": [
518      {
519        "name": "Photo.jpg",
520        "type": "file",
521        "file": {"url": "https://..."}
522      }
523    ]
524  }
525}
526```
527 
528**Note**: Updating files property replaces all existing files.
529 
530### Relation Value
531 
532```json
533{
534  "Related Tasks": {
535    "relation": [
536      {"id": "page-uuid-1"},
537      {"id": "page-uuid-2"}
538    ]
539  }
540}
541```
542 
543Maximum 100 related pages.
544 
545### Rollup Value (Read-Only)
546 
547Rollup values are computed and cannot be set directly.
548 
549Response example:
550 
551```json
552{
553  "Total": {
554    "type": "rollup",
555    "rollup": {
556      "type": "number",
557      "number": 42,
558      "function": "sum"
559    }
560  }
561}
562```
563 
564### Formula Value (Read-Only)
565 
566Formula values are computed and cannot be set directly.
567 
568Response example:
569 
570```json
571{
572  "Full Name": {
573    "type": "formula",
574    "formula": {
575      "type": "string",
576      "string": "John Doe"
577    }
578  }
579}
580```
581 
582Formula result types: `string`, `number`, `boolean`, `date`
583 
584### Created Time Value (Read-Only)
585 
586```json
587{
588  "Created": {
589    "type": "created_time",
590    "created_time": "2024-01-01T00:00:00.000Z"
591  }
592}
593```
594 
595### Created By Value (Read-Only)
596 
597```json
598{
599  "Creator": {
600    "type": "created_by",
601    "created_by": {
602      "object": "user",
603      "id": "user-uuid"
604    }
605  }
606}
607```
608 
609### Last Edited Time Value (Read-Only)
610 
611```json
612{
613  "Updated": {
614    "type": "last_edited_time",
615    "last_edited_time": "2024-01-15T12:00:00.000Z"
616  }
617}
618```
619 
620### Last Edited By Value (Read-Only)
621 
622```json
623{
624  "Editor": {
625    "type": "last_edited_by",
626    "last_edited_by": {
627      "object": "user",
628      "id": "user-uuid"
629    }
630  }
631}
632```
633 
634### Unique ID Value (Read-Only)
635 
636```json
637{
638  "ID": {
639    "type": "unique_id",
640    "unique_id": {
641      "prefix": "PROJ",
642      "number": 42
643    }
644  }
645}
646```
647 
648---
649 
650## Important Notes
651 
652### Property Value Limit
653 
654Property values in page objects have a **25 page reference limit**. Properties containing more than 25 page references (in `relation`, `people`, or `rollup` properties) only display the first 25 in standard responses.
655 
656Use the "Retrieve a page property" endpoint to get the complete list:
657 
658```bash
659curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
660  -H "Authorization: Bearer $NOTION_API_KEY" \
661  -H "Notion-Version: 2025-09-03"
662```
663 
664### Read-Only Properties
665 
666These properties cannot be set via API:
667- `created_time`
668- `created_by`
669- `last_edited_time`
670- `last_edited_by`
671- `rollup`
672- `formula`
673- `unique_id`
674 
675### Property References
676 
677Properties can be referenced by either:
678- **Name**: `"Status"` (may change if user renames)
679- **ID**: `"abc123"` (stable, recommended for integrations)
680 
681Get property IDs by retrieving the database schema.
682 
683### Null Values
684 
685To clear a property value, set it to `null`:
686 
687```json
688{
689  "Due Date": {
690    "date": null
691  }
692}
693```
694 
695For rich text/title, use an empty array:
696 
697```json
698{
699  "Description": {
700    "rich_text": []
701  }
702}
703```
704