# Get user info

`GET /user.info`

## Description

Resolve a v1 principal by ID, or look up a workspace member by email.

ID lookup resolves active or archived members, guests, and authorized
automated actors (classic bots, agents, assistants, and coworkers). The
response always includes `type: "user" | "bot"`; guests additionally have
`isGuest: true`. Groups, unknown IDs, and automated actors outside the
caller's Roam/account/owner boundary return `user_not_found`.

Email lookup remains workspace-member-only. Personal access tokens and the
MCP `user_info` tool may use ID lookup.

Provide either `id` or `email`, not both.

See [Identity & Principals](/docs/guides/identity-and-principals) for the
taxonomy, visibility rules, and directory-versus-hydration guidance.

**Required scope:** `user:read` (add `user:read.email` to look up by email or include email in response, `user:read.status` to expand presence status, availability, and `willReturn`)

**Access:** Organization and Personal.

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | query | string | No | A bare or tagged principal ID. Mutually exclusive with `email`. |
| `email` | query | string | No | The user's email address. Mutually exclusive with `id`. Requires `user:read.email` scope. |
| `expand` | query | string | No | Comma-separated list of additional fields to include. Supported: `status`, `available` (each requires `user:read.status`). Expanding `status` also returns `willReturn` when the user has a future out-o |

## Responses

### 200 - Principal info retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The principal's unique address identifier. |
| `type` | "user" | "bot" | Yes | Stable public principal type. All automated actors are `bot`. |
| `name` | string | Yes | Display name of the principal. |
| `imageUrl` | string | No | URL of the principal's profile image. |
| `email` | string | No | Email address for a member or guest (requires `user:read.email`). Omitted for bots. |
| `isGuest` | "true" | No | Present and true only for users without membership in the caller's account. |
| `isAdmin` | boolean | No | Whether a workspace member is an admin. Present for members even when false; omitted for guests and bots. |
| `jobTitle` | string | No | Workspace member's job title. Omitted for guests and bots. |
| `location` | string | No | Workspace member's location. Omitted for guests and bots. |
| `status` | "checkedIn" | "checkedOut" | No | User's current presence status. Only included when `expand=status` is requested and the `user:read.status` scope is granted. |
| `willReturn` | object | No | Out-of-office / "Will Return" status. Present only when `expand=status` is requested, the `user:read.status` scope is granted, and the user has a future return time. A user can be `checkedIn` and stil |
| `available` | boolean | No | Whether the user is currently available for visitors. Only included when `expand=available` is requested and the `user:read.status` scope is granted. |
| `botCode` | string | No | Classic bot persona identifier, when available. |
| `integrationId` | string | No | Integration/client identifier for an automated actor, when available. |

**willReturn**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `returnTime` | string | Yes | When the user is expected to return (RFC 3339). |
| `reason` | string | No | Optional absence message (e.g. "On Vacation"). |
| `outOfRoam` | boolean | No | When true, multi-day Out of Roam that persists across check-ins. When false or omitted, same-day Will Return Today. |

### 400 - Bad request. Common causes:
- Neither `id` nor `email` provided
- Both `id` and `email` provided


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Looking up by email requires `user:read.email` scope


### 404 - Principal not found, not authorized, or the ID belongs to a group (`user_not_found`).

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/user-info*