View my integrations

User object

The User object represents a user in a Notion workspace. Users include full workspace members, and bots. 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:

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.

Property

Updatable

Type

Description

Example value

object*

Display-only

"user"

Always "user"

"user"

id*

Display-only

string (UUID)

Unique identifier for this user.

"e79a0b74-3aba-4149-9f74-0bb5791a6ee6"

type

Display-only

string (optional, enum)

Type of the user. Possible values are "person" and "bot".

"person"

name

Display-only

string (optional)

User's name, as displayed in Notion.

"Avocado Lovelace"

avatar_url

Display-only

string (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:

Property

Updatable

Type

Description

Example value

person

Display-only

object

Properties only present for non-bot users.

person.email

Display-only

string

Email address of person. This is only present if an integration has user capabilities that allow access to email addresses.

"[email protected]"

Bots

User objects that represent bots have the type property set to "bot". These objects also have the following properties:

Property

Updatable

Type

Description

Example value

bot

Display-only

object

Properties only present for bot users.

If viewing your own bot with GET /v1/users/me or GET /v1/users/{{your_bot_id}}, this field will be populated with more information about the bot.

object

Information about who owns this bot.

owner.type

Display-only

string enum

The type of owner - either "workspace" or "user".

When viewing information about "your own" bot specifically - that is, the bot tied to the API token being used to call the API - the bot property will contain the following additional fields:

Property

Updatable

Type

Description

Example value

owner

Display-only

object

Information about who owns this bot.

owner.type

Display-only

string enum

The type of owner - either "workspace" or "user".

"user"

owner.workspace

Display-only

boolean

Always true. Only present if owner.type is "workspace".

true

owner.user

Display-only

object

A user object describing who owns this bot. Currently only "person" users can own bots. See the People reference above for more detail. The properties in the user object are based on the bot capabilities.

{ "object": "user", "id": "cb38e95d-00cf-4e7e-adce-974f4a44a547", "name": "Ada Lovelace", "avatar_url": null, "type": "person", "person": { "email": "[email protected]" } }