User

Users are the people who use our application. Each login is tied to a single user.

📄️ Add User

Creates a new user in the authenticated company and optionally adds them to teams via `teamMemberships` and assigns `directRoles`. Only Terros staff can set `user.companyId` to another company. Requires the `user:add` permission on the company or on one of the teams the user is added to. To add an existing user to a team, use `/team/member/add` instead.

📄️ Get User

Retrieves a single user, including their team memberships, primary team, and closer status. `userId` may be a User ID, email, account ID, or clientUserId; omit `userId` to get the authenticated user. Requires the `user:list` permission for the target user. Use `/user/profile` when you also need company details and roles, `/user/list` for many users, or `/user/search` to find users by name.

📄️ Get User Profile

Retrieves a user's full profile along with their company, including avatar, team memberships, roles, and closer status. `userId` may be a User ID, email, account ID, or clientUserId; omit `userId` to get the authenticated user's own profile (which also includes their permission map). Requires the `user:list` permission for the target user. Use `/user/get` when you only need the user record.

📄️ Remove User

Archives one user (`userId`) or several users (`userIds`). Archived users can be restored with `/user/update`. Requires the `user:manage` permission. Bulk removal always archives and only applies to users in your company; for a single user, `archive: false` permanently deletes instead, which is restricted to Tantalim users and unavailable in production. You cannot remove your own account or whitelisted users.

📄️ Update User

Updates fields on an existing user. Partial updates are supported: only the fields provided in `user` are changed, and `user.userId` defaults to the authenticated user when omitted. Send `startDate: null` to clear the start date. Requires the `user:update` permission for the target user, and archiving or restoring a user (`isDeleted`) also requires `user:manage`. Fields listed in the company `lockedUserFields` preference can be changed only by callers with `user:manage` on the user, and changing your own locked fields needs company-wide `user:manage`. A request from anyone else that changes a locked field is rejected and nothing is saved. Locking `avatar` instead withholds `uploadAvatarUrl` from `/user/profile` under the same rule. To change team membership or roles on a team, use `/team/member/add` or `/team/member/update` instead.

📄️ List Users

Lists users visible to the authenticated user. Provide `userIds` to fetch specific users from the database, `teamId` to list users on that team and its downline teams, or neither to list all users you can see in the company. Without `userIds`, role data comes from the search index and can be stale; `/user/get` is the source of truth for one user's role assignments. Archived users are excluded unless `showArchived` is set. Requires the `user:list` permission. Use `/user/search` to find users by name, or `/user/get` for full details on one user.

📄️ Search Users

Searches users visible to the authenticated user by name or phone number, with optional company, team, closer status, archive, downline, and result-size filters. Returns up to 20 users by default and excludes archived users unless `archived` is set. Without `companyId` it searches only your own company, so use `/search` to find users in other companies. Use this to find a user ID from a name; use `/user/list` to list every user on a team or company, or `/search` to search across multiple entity types at once.

📄️ Clear User Sign-in Lockout

Clears the lockout a user gets after too many failed sign-in attempts, from every IP address, so they can sign in again right away. Requires the `user:manage` permission for the user. Use it when a user reports being locked out. It does not change their password, and it succeeds even when the user is not locked out.

📄️ User Webhook

This webhook is triggered when an action is taken on a user.