A page object is made up of page properties that contain data about the page. You can use the Notion API to retrieve the identifier, type, and value of page properties.

The Retrieve a page endpoint returns all of a page object’s properties. The endpoint limits the page response object to 25 references across all page properties. If a page object’s Parent object is a database, then the property values conform to the database property schema. If a page object is not part of a database, then the only property value available for that page is its title.

The Retrieve a page property item endpoint returns information for a single property.

Each page property value object contains the following fields:

FieldTypeDescriptionExample value
"id"stringAn underlying identifier for the property. id may be a UUID, but it’s often a short random string.

id may be used in place of name when creating or updating pages.

id remains constant when the property name changes.
"f%5C%5C%3Ap"
"type"string (enum)The type of the property in the page object. Possible type values are:

- "checkbox"
- "created_by"
- "created_time"
- "date"
- "email"
- "files"
- "formula"
- "last_edited_by"
- "last_edited_time"
- "multi_select"
- "number"
- "people”
- "phone_number"
- "relation"
- "rollup"
- "rich_text"
- "select"
- "status"
- "title"
- "url"

Refer to specific type sections below for details on type-specific values.
"rich text"

Each page property value contains additional values specific to its type. The following sections describe these type-specific values and share example responses from the Retrieve a page and Retrieve a page property item endpoints for each type.

👍

Interact with page property values

Create or modify property values via the Create a page and Update page endpoints.

Checkbox

FieldTypeDescriptionExample value
"checkbox"booleanWhether the checkbox is checked (true) or unchecked (false).true
{
  "Example checkbox property": {
    "id": "ZI%40W",
    "type": "checkbox",
    "checkbox": false
  }
}
{
  "object": "property_item",
  "type": "checkbox",
  "id": "ZI%40W",
  "checkbox": false
}

Created by

FieldTypeDescriptionExample value
"created_by"objectA user object containing information about the user who created the page.

"created_by" can’t be updated.
Refer to the example response objects below.
{
  "Example created by property": {
    "object": "user",
    "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
    "name": "Ada Lovelace",
    "avatar_url": null,
    "type": "person",
    "person": {
      "email": "[email protected]"
    }
  }
}
{
  "object": "property_item",
  "type": "created_by",
  "id": "%3DDTq",
  "created_by": {
    "object": "user",
    "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
    "name": "Ada Lovelace",
    "avatar_url": null,
    "type": "person",
    "person": {
      "email": "[email protected]"
    }
  }
}

Created time

FieldTypeDescriptionExample value
"created_time"string (ISO 8601 date and time)The date and time that the page was created.

The created_time value can’t be updated.
"2022-10-12T16:34:00.000Z"
{
  "Example created time property": {
    "id": "eB_%7D",
    "type": "created_time",
    "created_time": "2022-10-12T16:34:00.000Z"
  }
}
{
  "object": "property_item",
  "type": "created_time",
  "id": "eB_%7D",
  "created_time": "2022-10-12T16:34:00.000Z"
}

Date

If the type of a page property value is "date", then the property value contains a "date" object with the following fields:

FieldTypeDescriptionExample value
"end"string (ISO 8601 date and time)(Optional) A string representing the end of a date range.

If the value is null, then the date value is not a range.
"2020-12-08T12:00:00Z"
"start"string (ISO 8601 date and time)A date, with an optional time.

If the "date" value is a range, then start represents the start of the range.
"2020-12-08T12:00:00Z”
{
  "Example Date property": {
    "id": "M%3BBw",
    "type": "date",
    "date": {
      "start": "2022-10-14",
      "end": null,
      "time_zone": null
    }
  }
}
{
  "object": "property_item",
  "type": "date",
  "id": "M%3BBw",
  "date": {
    "start": "2022-10-14",
    "end": null,
    "time_zone": null
  }
}

Email

FieldTypeDescriptionExample value
"email"stringA string describing an email address."[email protected]"
{
  "Example email property": {
    "id": "y%5C%5E_",
    "type": "email",
    "email": "[email protected]"
  }
}
{
  "object": "property_item",
  "type": "email",
  "id": "y%5C%5E_",
  "email": "[email protected]"
}

Files

FieldTypeDescriptionExample value
"files"array of file objectsAn array of objects containing information about the files.Refer to the example response objects below.
{
  "Example files & media property": {
    "id": "tJPS",
    "type": "files",
    "files": [
      {
        "name": "My_test_image.png",
        "type": "file",
        "file": {
          "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject",
          "expiry_time": "2022-10-24T21:52:11.228Z"
        }
      },
      {
        "name": "https://images.unsplash.com/photo-1525310072745-f49212b5ac6d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1065&q=80",
        "type": "external",
        "external": {
          "url": "https://images.unsplash.com/photo-1525310072745-f49212b5ac6d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1065&q=80"
        }
      }
    ]
  }
}
{
  "object": "property_item",
  "type": "files",
  "id": "tJPS",
  "files": [
    {
      "name": "My_test_image.png",
      "type": "file",
      "file": {
        "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject",
        "expiry_time": "2022-10-24T22:49:22.765Z"
      }
    },
    {
      "name": "https://images.unsplash.com/photo-1525310072745-f49212b5ac6d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1065&q=80",
      "type": "external",
      "external": {
        "url": "https://images.unsplash.com/photo-1525310072745-f49212b5ac6d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1065&q=80"
      }
    }
  ]
}

📘

When updating a file property, the value is overwritten by the array of files passed.

Although Notion doesn't support uploading files, if you pass a file object containing a file hosted by Notion, it remains one of the files. To remove any file, just don't pass it in the update response.

Formula

Formula property value objects represent the result of evaluating a formula described in the
database's properties.

If the type of a page property value is "formula", then the property value contains a "formula" object with the following fields:

FieldTypeDescriptionExample value
"type"string (enum)A string indicating the data type of the result of the formula. Possible type values are:

- "boolean"
- "date"
- "number"
- "string"
"number"
"boolean" || "date" || "number" || "string""boolean" || "date" || "number" || "string"The value of the result of the formula.

The value can’t be updated directly via the API.
"number": 42
{
  "Example formula property": {
    "id": "CSoE",
    "type": "formula",
    "formula": {
      "type": "number",
      "number": 42
    }
  }
}

📘

The Retrieve a page endpoint returns a maximum of 25 inline page or person references for a formula property. If a formula property includes more than 25 references, then you can use the Retrieve a page property item endpoint for the specific formula property to get its complete list of references.

{
  "Example formula property": {
    "id": "CSoE",
    "type": "formula",
    "formula": {
      "type": "number",
      "number": 42
    }
  }
}

Last edited by

FieldTypeDescriptionExample value
"last_edited_by"objectA user object containing information about the user who last updated the page.

"last_edited_by" can’t be updated.
Refer to the example response objects below.
{
  "Example last edited by property": {
    "id": "uGNN",
    "type": "last_edited_by",
    "last_edited_by": {
      "object": "user",
      "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
      "name": "Ada Lovelace",
      "avatar_url": null,
      "type": "person",
      "person": {
        "email": "[email protected]"
      }
    }
  }
}
{
  "object": "property_item",
  "type": "last_edited_by",
  "id": "uGNN",
  "last_edited_by": {
    "object": "user",
    "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
    "name": "Ada Lovelace",
    "avatar_url": null,
    "type": "person",
    "person": {
      "email": "[email protected]"
    }
  }
}

Last edited time

FieldTypeDescriptionExample value
"last_edited_time"string (ISO 8601 date and time)The date and time that the page was last edited.

The last_edited_time value can’t be updated.
"2022-10-12T16:34:00.000Z"
{
  "Example last edited time property": {
    "id": "%3Defk",
    "type": "last_edited_time",
    "last_edited_time": "2022-10-24T22:56:00.000Z"
  }
}
{
  "object": "property_item",
  "type": "last_edited_time",
  "id": "%3Defk",
  "last_edited_time": "2022-10-24T22:56:00.000Z"
}

Multi-select

If the type of a page property value is "multi_select", then the property value contains a "multi_select" array with the following fields:

FieldTypeDescriptionExample value
"id"string (UUIDv4)The ID of the option.

You can use "id" or "name" to update a multi-select property.
"b3d773ca-b2c9-47d8-ae98-3c2ce3b2bffb"
"name"stringThe name of the option as it appears in Notion.

If the multi-select database property does not yet have an option by that name, then the name 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.
"JavaScript"
"color"string (enum)Color of the option. Possible "color" values are: 

- "default"
- "gray"
"brown"
- "red"
- "orange"
- "yellow"
- "green"
- "blue"
- "purple"
- "pink"

Defaults to "default". The "color" value can’t be updated via the API.
"red"
{
  "Example multi-select property": {
    "id": "QyRn",
    "type": "multi_select",
    "multi_select": [
      {
        "id": "tC;=",
        "name": "TypeScript",
        "color": "purple"
      },
      {
        "id": "e4413a91-9f84-4c4a-a13d-5b4b3ef870bb",
        "name": "JavaScript",
        "color": "red"
      }
    ]
  }
}
{
  "object": "property_item",
  "type": "multi_select",
  "id": "QyRn",
  "multi_select": [
    {
      "id": "tC;=",
      "name": "TypeScript",
      "color": "purple"
    },
    {
      "id": "e4413a91-9f84-4c4a-a13d-5b4b3ef870bb",
      "name": "JavaScript",
      "color": "red"
    }
  ]
}

Number

FieldTypeDescriptionExample value
"number"numberA number representing some value.1234
{
  "Example number property": {
    "id": "WPj%5E",
    "type": "number",
    "number": 42
  }
}
{
  "object": "property_item",
  "type": "number",
  "id": "WPj%5E",
  "number": 42
}

People

FieldTypeDescriptionExample value
"people"array of user objectsAn array of user objects.Refer to the example response objects below.
{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "people",
      "id": "%7BLUX",
      "people": [
    {
      "object": "user",
      "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
      "name": "Ada Lovelace",
      "avatar_url": null,
      "type": "person",
      "person": {
        "email": "[email protected]"
      }
    },
    {
      "object": "user",
      "id": "c2g20451-2b67-1c31-8c79-6345265bc31r",
      "name": "Grace Hopper",
      "avatar_url": null,
      "type": "person",
      "person": {
        "email": "[email protected]"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "%7BLUX",
    "next_url": null,
    "type": "people",
    "people": {}
  }
}

📘

The Retrieve a page endpoint can’t be guaranteed to return more than 25 people per people page property. If a people page property includes more than 25 people, then you can use the Retrieve a page property item endpoint for the specific people property to get a complete list of people.

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "people",
      "id": "%7BLUX",
      "people": [
    {
      "object": "user",
      "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
      "name": "Ada Lovelace",
      "avatar_url": null,
      "type": "person",
      "person": {
        "email": "[email protected]"
      }
    },
    {
      "object": "user",
      "id": "c2g20451-2b67-1c31-8c79-6345265bc31r",
      "name": "Grace Hopper",
      "avatar_url": null,
      "type": "person",
      "person": {
        "email": "[email protected]"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "%7BLUX",
    "next_url": null,
    "type": "people",
    "people": {}
  }
}

Phone number

FieldTypeDescriptionExample value
"phone_number"stringA string representing a phone number. No phone number format is enforced."415-867-5309"
{
  "Example phone number property": {
    "id": "%5DKhQ",
    "type": "phone_number",
    "phone_number": "415-867-5309"
  }
}
{
  "object": "property_item",
  "type": "phone_number",
  "id": "%5DKhQ",
  "phone_number": "415-867-5309"
}

Relation

FieldTypeDescriptionExample value
"relation"an array of page referencesAn array of related page references. A page reference is an object with an id key and a string value (UUIDv4) corresponding to a page ID in another database.Refer to the example response objects below.
"has_more"booleanIf a relation has more than 25 references, then the has_more value for the relation in the response object is true. If a relation doesn’t exceed the limit, then has_more is false.false

📘

Note that updating a relation property value with an empty array will clear the list.

{
  "Example relation property": {
    "id": "%40NRE",
    "type": "relation",
    "relation": [],
    "has_more": false
  }
}
{
  "object": "list",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "%40NRE",
    "next_url": null,
    "type": "relation",
    "relation": {}
  }
}

Rollup

If the type of a page property value is "rollup", then the property value contains a "rollup" object with the following fields:

FieldTypeDescriptionExample value
"type""number" || "date" || "array" || "unsupported" || "incomplete"The value type of the calculated rollup."number"
"number" || "date" || "array" || "unsupported" || "incomplete"Corresponds to the field.

For example, if the field is "number", then the type of the value is number.
The value of the calculated rollup.

The value can't be directly updated via the API.
1234
"function"string (enum)The function that is evaluated for every page in the relation of the rollup. Possible "function" values are:

- "average"
- "checked"
- "count"
- "count_per_group"
- "count_values"
- "date_range"
- "earliest_date"
- "empty"
- "latest_date"
- "max"
- "median"
- "min"
- "not_empty"
- "percent_checked"
- "percent_empty"
- "percent_not_empty"
- "percent_per_group"
- "percent_unchecked"
- "range"
- "show_original"
- "show_unique"
- "sum"
- "unchecked"
- "unique"
"sum"
{
  "Example rollup property": {
    "id": "WD%3Cs",
    "type": "rollup",
    "rollup": {
      "type": "number",
      "number": 42,
      "function": "sum"
    }
  }
}
{
  "object": "list",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "WD%3Cs",
    "next_url": null,
    "type": "rollup",
    "rollup": {
      "type": "number",
      "number": 42,
      "function": "sum"
    }
  }
}

📘

Refer to the Retrieve a page property item endpoint documentation for more details on querying data about rollup property values.

Rich text

FieldTypeDescriptionExample value
"type"an array of rich text objectsAn array of rich text objectsRefer to the example response objects below.
{
  "Example rich text property": {
    "id": "HbZT",
    "type": "rich_text",
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "There is some ",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "There is some ",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": "text",
          "link": null
        },
        "annotations": {
          "bold": true,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "text",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": " in this property!",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": " in this property!",
        "href": null
      }
    ]
  }
}

📘

The Retrieve a page endpoint returns a maximum of 25 populated inline page or person references for a rich_text property. If a rich_text property includes more than 25 references, then you can use the Retrieve a page property item endpoint for the specific rich_text property to get its complete list of references.

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "rich_text",
      "id": "HbZT",
      "rich_text": {
        "type": "text",
        "text": {
          "content": "There is some ",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "There is some ",
        "href": null
      }
    },
    {
      "object": "property_item",
      "type": "rich_text",
      "id": "HbZT",
      "rich_text": {
        "type": "text",
        "text": {
          "content": "text",
          "link": null
        },
        "annotations": {
          "bold": true,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "text",
        "href": null
      }
    },
    {
      "object": "property_item",
      "type": "rich_text",
      "id": "HbZT",
      "rich_text": {
        "type": "text",
        "text": {
          "content": " in this property!",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": " in this property!",
        "href": null
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "HbZT",
    "next_url": null,
    "type": "rich_text",
    "rich_text": {}
  }
}

Select

If the type of a page property value is "select", then the property value contains a "select" object with the following fields:

PropertyTypeDescriptionExample value
idstring (UUIDv4)The ID of the option.

You can use "id" or "name" to update a select property.
"b3d773ca-b2c9-47d8-ae98-3c2ce3b2bffb"
namestringThe name of the option as it appears in Notion.

If the select database property doesn't have an option by that name yet, then the name is added to the database schema if the integration also has write access to the parent database.

Note: Commas (",") are not valid for select values.
"jQuery"
colorstring (enum)The color of the option. Possible "color" values are: 

- "default"
- "gray"
"brown"
- "red"
- "orange"
- "yellow"-"green"-"blue"-"purple"-"pink" Defaults to "default". The "color"` value can’t be updated via the API.
"red"
{
  "Example select property": {
    "id": "Yc%3FJ",
    "type": "select",
    "select": {
      "id": "[email protected]_",
      "name": "jQuery",
      "color": "purple"
    }
  }
}
{
  "object": "property_item",
  "type": "select",
  "id": "Yc%3FJ",
  "select": {
    "id": "[email protected]_",
    "name": "jQuery",
    "color": "purple"
  }
}

Status

If the type of a page property value is "status", then the property value contains a "status" object with the following fields:

PropertyTypeDescriptionExample value
idstring (UUIDv4)The ID of the option."b3d773ca-b2c9-47d8-ae98-3c2ce3b2bffb"
namestringThe name of the option as it appears in Notion."In progress"
colorstring (enum)The color of the option. Possible "color" values are: 

- "default"
- "gray"
"brown"
- "red"
- "orange"
- "yellow"-"green"-"blue"-"purple"-"pink" Defaults to "default". The "color"` value can’t be updated via the API.
"red"
{
  "Example status property": {
    "id": "Z%3ClH",
    "type": "status",
    "status": {
      "id": "539f2705-6529-42d8-a215-61a7183a92c0",
      "name": "In progress",
      "color": "blue"
    }
  }
}
{
  "object": "property_item",
  "type": "status",
  "id": "Z%3ClH",
  "status": {
    "id": "539f2705-6529-42d8-a215-61a7183a92c0",
    "name": "In progress",
    "color": "blue"
  }
}

Title

FieldTypeDescriptionExample value
"title"an array of rich text objectsAn array of rich text objects.Refer to the example response objects below.
{
  "Example title property": {
    "id": "title",
    "type": "title",
    "title": [
      {
        "type": "text",
        "text": {
          "content": "This is my title",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "This is my title",
        "href": null
      }
    ]
  }
}

📘

The Retrieve a page endpoint returns a maximum of 25 inline page or person references for a title property. If a title property includes more than 25 references, then you can use the Retrieve a page property item endpoint for the specific title property to get its complete list of references.

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "title",
      "id": "title",
      "title": {
        "type": "text",
        "text": {
          "content": "This is my title",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "This is my title",
        "href": null
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "property_item",
  "property_item": {
    "id": "title",
    "next_url": null,
    "type": "title",
    "title": {}
  }
}

URL

FieldTypeDescriptionExample value
"url"stringA string that describes a web address."https://developers.notion.com/"
{
  "Example URL property": {
    "id": "bB%3D%5B",
    "type": "url",
    "url": "https://developers.notion.com/"
  }
}
{
    "object": "property_item",
    "type": "url",
    "id": "bB%3D%5B",
    "url": "https://developers.notion.com/"
}