V2
Get User
Fetch basic user profile data and return email only when the token has permission.
Get User
Use Case
Use this endpoint when you need the basic profile for a user referenced by pages, blocks, database properties, or audit fields.
Endpoint
| Item | Value |
|---|---|
| Method | GET |
| Path | /v2/users/:user_id |
| Request body | None |
| Returns | user |
| Scope | users.read |
Permissions
Requires users.read. The optional users.email.read scope controls whether person.email contains an email address or null.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id |
string | Yes | User ID. |
Response Example
{
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
"type": "person",
"name": "Alex Chen",
"avatar_url": "https://example.com/avatar.png",
"person": {
"email": "alex@example.com"
}
}
Behavior
- Without
users.email.read,person.emailisnull. - Users outside the accessible workspace return
404 not_found. - Use user references in other objects with this endpoint when you need display names or email addresses.
Errors
401 unauthorized: invalid or expired token.403 forbidden: missingusers.read.404 not_found: user does not exist or is not accessible.