A property value defines the identifier, type, and value of a page property in a page object. It's used when retrieving and updating pages ex: Create and Update pages.
Property values in the page object have a 25 page reference limit
Any property value that has uses other pages in its value will only use the first 25 page references. Use the Retrieve a page property endpoint to paginate through the full value.
All property values
Each page property value object contains the following keys. In addition, it contains a key corresponding with the value of type
. The value is an object containing type-specific data. The type-specific data are described in the sections below.
Property | Type | Description | Example value |
---|---|---|---|
|
| Underlying identifier for the property. This identifier is guaranteed to remain constant when the property name changes. It may be a UUID, but is often a short random string. The |
|
|
| Type of the property. Possible values are |
|
Title property values
Title property value objects contain an array of rich text objects within the title
property.
{
"Name": {
"title": [
{
"type": "text",
"text": {
"content": "The title"
}
}
]
}
}
{
"title": {
"title": [
{
"type": "rich_text",
"rich_text": {
"content": "The title"
}
}
]
}
}
Rich Text property values
Rich Text property value objects contain an array of rich text objects within the rich_text
property.
{
"Details": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Some more text with "
}
},
{
"type": "text",
"text": {
"content": "some"
},
"annotations": {
"italic": true
}
},
{
"type": "text",
"text": {
"content": " "
}
},
{
"type": "text",
"text": {
"content": "fun"
},
"annotations": {
"bold": true
}
},
{
"type": "text",
"text": {
"content": " "
}
},
{
"type": "text",
"text": {
"content": "formatting"
},
"annotations": {
"color": "pink"
}
}
]
}
}
{
"D[X|": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Some more text with "
}
},
{
"type": "text",
"text": {
"content": "some"
},
"annotations": {
"italic": true
}
},
{
"type": "text",
"text": {
"content": " "
}
},
{
"type": "text",
"text": {
"content": "fun"
},
"annotations": {
"bold": true
}
},
{
"type": "text",
"text": {
"content": " "
}
},
{
"type": "text",
"text": {
"content": "formatting"
},
"annotations": {
"color": "pink"
}
}
]
}
}
Number property values
Number property value objects contain a number within the number
property.
{
"Quantity": {
"number": 1234
}
}
{
"[email protected]": {
"number": 1234
}
}
Select property values
Select property value objects contain the following data within the select
property:
Property | Type | Description | Example value |
---|---|---|---|
|
| ID of the option. When updating a select property, you can use either |
|
|
| Name of the option as it appears in Notion. If the select database property does not yet have an option by that name, it will be added to the database schema if the integration also has write access to the parent database. Note: Commas (",") are not valid for select values. |
|
|
| Color of the option. Possible values are: Not currently editable. |
|
{
"Option": {
"select": {
"name": "Option 1"
}
}
}
{
"XMqQ": {
"select": {
"id": "c3406b80-bda4-45e0-add2-2748ac1527b"
}
}
}
Multi-select property values
Multi-select property value objects contain an array of multi-select option values within the multi_select
property.
Multi-select option values
Property | Type | Description | Example value |
---|---|---|---|
|
| ID of the option. When updating a multi-select property, you can use either |
|
|
| Name of the option as it appears in Notion. If the multi-select database property does not yet have an option by that name, it will be added to the database schema if the integration also has write access to the parent database. Note: Commas (",") are not valid for select values. |
|
|
| Color of the option. Possible values are: Not currently editable. |
|
{
"Tags": {
"multi_select": [
{
"name": "B"
},
{
"name": "C"
}
]
}
}
{
"[email protected]": {
"multi_select": [
{
"id": "3d3ca089-f964-4831-a8a2-0c6d746f4162"
},
{
"id": "1919ba02-1bf3-4e73-8832-8c0020f17363"
}
]
}
}
Date property values
Date property value objects contain the following data within the date
property:
Property | Type | Description | Example value |
---|---|---|---|
| string (ISO 8601 date and time) | An ISO 8601 format date, with optional time. |
|
| string (optional, ISO 8601 date and time) | An ISO 8601 formatted date, with optional time. Represents the end of a date range. If |
|
| string (optional, enum) | Time zone information for When time zone is provided, If |
|
{
"Shipment Time": {
"date": {
"start": "2021-05-11T11:00:00.000-04:00"
}
}
}
{
"CbFP": {
"date": {
"start": "2021-05-11T11:00:00.000-04:00"
}
}
}
{
"Preparation Range": {
"date": {
"start": "2021-04-26",
"end": "2021-05-07"
}
}
}
{
"\\rm}": {
"date": {
"start": "2021-04-26",
"end": "2021-05-07"
}
}
}
{
"Delivery Time": {
"date": {
"start": "2020-12-08T12:00:00Z",
"time_zone": "America/New_York"
}
}
}
{
"DgRt": {
"date": {
"start": "2020-12-08T12:00:00Z",
"time_zone": "America/New_York"
}
}
}
Formula property values
Formula property value objects represent the result of evaluating a formula described in the
database's properties. These objects contain a type
key and a key corresponding with the value of type
. The value of a formula cannot be updated directly.
Formula values may not match the Notion UI.
Formulas returned in page objects are subject to a 25 page reference limitation. The Retrieve a page property endpoint should be used to get an accurate formula value.
{
"Formula": {
"id": "1lab",
"formula": {
"type": "number",
"number": 1234
}
}
}
Property | Type | Description |
---|---|---|
|
|
String formula property values
String formula property values contain an optional string within the string
property.
Number formula property values
Number formula property values contain an optional number within the number
property.
Boolean formula property values
Boolean formula property values contain a boolean within the boolean
property.
Date formula property values
Date formula property values contain an optional date property value within the date
property.
Relation property values
Relation property value objects contain an array of page references within the relation
property. A page reference is an object with an id
property, with a string value (UUIDv4) corresponding to a page ID in another database. Updating with an empty array will clear the list. Note: a relation
property has a maximum of 100 pages.
{
"Project": {
"relation": [
{
"id": "1d148a9e-783d-47a7-b3e8-2d9c34210355"
}
]
}
}
{
"mODt": {
"relation": [
{
"id": "1d148a9e-783d-47a7-b3e8-2d9c34210355"
}
]
}
}
Rollup property values
Rollup property value objects represent the result of evaluating a rollup described in the
database's properties. These objects contain a type
key and a key corresponding with the value of type
. The value of a rollup cannot be updated directly.
{
"Rollup": {
"id": "aJ3l",
"rollup": {
"type": "number",
"number": 1234,
"function": "sum"
}
}
}
Rollup values may not match the Notion UI.
Rollups returned in page objects are subject to a 25 page reference limitation. The Retrieve a page property endpoint should be used to get an accurate formula value.
String rollup property values
String rollup property values contain an optional string within the string
property.
Number rollup property values
Number rollup property values contain a number within the number
property.
Date rollup property values
Date rollup property values contain a date property value within the date
property.
Array rollup property values
Array rollup property values contain an array of number
, date
, or string
objects within the results
property.
People property values
People property value objects contain an array of user objects within the people
property.
{
"Owners": {
"people": [
{
"object": "user",
"id": "3e01cdb8-6131-4a85-8d83-67102c0fb98c"
},
{
"object": "user",
"id": "b32c006a-2898-45bb-abd2-de095f354592"
}
]
}
}
{
"Owners": {
"people": [
{
"object": "user",
"id": "3e01cdb8-6131-4a85-8d83-67102c0fb98c"
},
{
"object": "user",
"id": "b32c006a-2898-45bb-abd2-de095f354592"
}
]
}
}
Files property values
File property value objects contain an array of file references within the files
property. A file reference is an object with a File Object and name
property, with a string value corresponding to a filename of the original file upload (i.e. "Whole_Earth_Catalog.jpg"
).
{
"Files": {
"files": [
{
"type": "external",
"name": "Space Wallpaper",
"external": {
"url": "https://website.domain/images/space.png"
}
}
]
}
}
When updating a file property, the value will be overwritten by the array of files passed.
Although we do not support uploading files, if you pass a
file
object containing a file hosted by Notion, it will remain one of the files. To remove any file, just do not pass it in the update response.
Checkbox property values
Checkbox property value objects contain a boolean within the checkbox
property.
{
"Done?": {
"checkbox": true
}
}
{
"RirO": {
"checkbox": true
}
}
URL property values
URL property value objects contain a non-empty string within the url
property. The string describes a web address (i.e. "http://worrydream.com/EarlyHistoryOfSmalltalk/"
).
{
"Website": {
"url": "https://notion.so/notiondevs"
}
}
{
"<tdn": {
"url": "https://notion.so/notiondevs"
}
}
Email property values
Email property value objects contain a string within the email
property. The string describes an email address (i.e. "[email protected]"
).
{
"Shipper's Contact": {
"email": "[email protected]"
}
}
{
"}=RV": {
"email": "[email protected]"
}
}
Phone number property values
Phone number property value objects contain a string within the phone_number
property. No structure is enforced.
{
"Shipper's No.": {
"phone_number": "415-000-1111"
}
}
{
"_A<p": {
"phone_number": "415-000-1111"
}
}
Created time property values
Created time property value objects contain a string within the created_time
property. The string contains the date and time when this page was created. It is formatted as an ISO 8601 date time string (i.e. "2020-03-17T19:10:04.968Z"
). The value of created_time
cannot be updated. See the Property Item Object to see how these values are returned.
Created by property values
Created by property value objects contain a user object within the created_by
property. The user object describes the user who created this page. The value of created_by
cannot be updated. See the Property Item Object to see how these values are returned.
Last edited time property values
Last edited time property value objects contain a string within the last_edited_time
property. The string contains the date and time when this page was last updated. It is formatted as an ISO 8601 date time string (i.e. "2020-03-17T19:10:04.968Z"
). The value of last_edited_time
cannot be updated. See the Property Item Object to see how these values are returned.
Last edited by property values
Last edited by property value objects contain a user object within the last_edited_by
property. The user object describes the user who last updated this page. The value of last_edited_by
cannot be updated. See the Property Item Object to see how these values are returned.