1. User
Notion API - Public Beta (English)
  • Introduction
  • Integration capabilities
  • Request limits
  • Status codes
  • ENDPOINTS
    • Authentication
      • Authentication
      • Token
    • Blocks
      • Delete a block
      • Append block children
      • Retrieve a block
      • Update a block
      • Retrieve block children
    • Databases
      • Filter database entries
      • Sort database entries
      • Update database properties
      • Retrieve a database
      • Update a database
      • Query a database
    • Pages
      • Archive a page
      • Retrieve a page property item
      • Create a page
      • Retrieve a Page
      • Update Page properties
    • Users
      • List all users
      • Retrieve your token's bot user
      • Retrieve a user
    • Comments
      • Create comment
      • Retrieve comments
    • Search
      • Search optimizations and limitations
      • Search by title
  • OBJECTS
    • Block
    • Comment
    • Unfurl attribute object for Link Previews
    • Page
      • Page
      • Page properties
    • Database
      • Database
      • Database properties
    • User
      • User
      • Comment
    • Other
      • Emoji object
      • File object
      • Parent object
      • Rich text object
  • Versioning
    • Versioning
    • Changes by version
  • ENDPOINTS Copy
    • Authentication
      • Authentication
      • Token
    • Blocks
      • Retrieve a block
      • Update a block
      • Retrieve block children
      • Delete a block
      • Append block children
    • Databases
      • Filter database entries
      • Sort database entries
      • Update database properties
      • Retrieve a database
      • Update a database
      • Query a database
      • Create a database
    • Pages
      • Archive a page
      • Retrieve a Page
      • Update Page properties
      • Retrieve a page property item
      • Create a page
    • Users
      • Retrieve a user
      • List all users
      • Retrieve your token's bot user
    • Comments
      • Create comment
      • Retrieve comments
  1. User

User

The User object represents a user in a Notion workspace. Users include full workspace members, and integrations. Guests are not included. You can find more information about members and guests in this guide.

📘Provisioning users and groups using SCIM#

The SCIM API is available for workspaces in Notion's Enterprise Plan. Learn more about using SCIM with Notion.

📘Setting up single sign-on (SSO) with Notion#

Single sign-on (SSO) can be configured for workspaces in Notion's Enterprise Plan. Learn more about SSO with Notion.

Where user objects appear in the API#

User objects appear in the API in nearly all objects returned by the API, including:
Block object under created_by and last_edited_by.
Page object under created_by and last_edited_by and in people property items.
Database object under created_by and last_edited_by.
Rich text object, as user mentions.
Property object when the property is a people property.
User objects will always contain object and id keys, as described below. The remaining properties may appear if the user is being rendered in a rich text or page property context, and the bot has the correct capabilities to access those properties. For more about capabilities, see the Capabilities guide and the Authorization guide.

All users#

These fields are shared by all users, including people and bots. Fields marked with * are always present.
PropertyUpdatableTypeDescriptionExample value
object*Display-only"user"Always "user""user"
id*Display-onlystring (UUID)Unique identifier for this user."e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
typeDisplay-onlystring (optional, enum)Type of the user. Possible values are "person" and "bot"."person"
nameDisplay-onlystring (optional)User's name, as displayed in Notion."Avocado Lovelace"
avatar_urlDisplay-onlystring (optional)Chosen avatar image."https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg"

People#

User objects that represent people have the type property set to "person". These objects also have the following properties:
PropertyUpdatableTypeDescriptionExample value
personDisplay-onlyobjectProperties only present for non-bot users.
person.emailDisplay-onlystringEmail address of person. This is only present if an integration has user capabilities that allow access to email addresses."avo@example.org"

Bots#

A user object's type property is"bot" when the user object represents a bot. A bot user object has the following properties:
PropertyUpdatableTypeDescriptionExample value
botDisplay-onlyobjectIf you're using GET /v1/users/me or GET /v1/users/{{your_bot_id}}, then this field returns data about the bot, including owner, owner.type, and workspace_name. These properties are detailed below.{ "object": "user", "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf", "name": "Test Integration", "avatar_url": null, "type": "bot", "bot": { "owner": { "type": "workspace", "workspace": true }, "workspace_name": "Ada Lovelace’s Notion" } }
ownerDisplay-onlyobjectInformation about who owns this bot.{ "type": "workspace", "workspace": true }
owner.typeDisplay-onlystring enumThe type of owner, either "workspace" or "user"."workspace"
workspace_nameDisplay-onlystring enumIf the owner.type is "workspace", then workspace.name identifies the name of the workspace that owns the bot. If the owner.type is "user", then workspace.name is null."Ada Lovelace’s Notion"
Modified at 2023-04-28 06:48:13
Previous
Database properties
Next
Comment
Built with