Get Multiple Users by IDs
/v1/users/{ids}org.permission.user.readorg.user.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves multiple users in a single request using a list of unique user IDs separated by a comma.
Users
A user is an account that works in your Kustomer org, such as an agent, an admin or a collaborator, or the machine user behind an API key. Users are the people and integrations doing the support work, as opposed to customers, who receive it.
Users appear throughout Kustomer as the authors of messages and notes, the assignees of conversations, and the members of teams. Admins invite people from Kustomer's user settings or with POST /v1/users, which creates the account and emails an invitation. The user stays pending until they accept it. Creating an API key creates a machine user too, and anything the key changes is attributed to that user. Users aren't deleted: deactivating one keeps their history and lets you restore them later.
User types
userType |
Who |
|---|---|
user |
A full user, such as an agent or admin |
limited |
A collaborator, with limited access |
machine |
The machine user behind an API key |
GET /v1/users filters with userType, pending (true for invitations not yet accepted), deleted (true for deactivated users) or email. Use one filter per request; the only combination that works is deleted with userType, such as userType=user&deleted=false for active full users.
Roles and role groups
What a user can do comes from roles and from role groups. A user can have one role group assigned directly in roleGroups, and gets more through their teams. When you invite or update a user, you can't give them more permissions than you have yourself: roles beyond your own are filtered out automatically.
Current user and deactivation
/v1/users/current is the user behind the token you're calling with: the person for a session or OAuth token, or the machine user for an API key. It works with any valid token, and it's the easy way to find an API key's machine user ID, for example to give it an avatar. PUT /v1/users/current updates your own profile, and accepts a new password together with currentPassword.
To deactivate someone, send PUT /v1/users/{id} with deleted: true. Send deleted: null to restore them.
Which endpoint to use
| To | Call |
|---|---|
| Find out who the token you're using belongs to | GET /v1/users/current |
| Update your own profile or password | PUT /v1/users/current |
| List or search users by type, status or email | GET /v1/users |
| Read one user | GET /v1/users/{id} |
| Read several users at once, such as a team's members | GET /v1/users/{ids}, with comma-separated IDs |
| Invite a new user | POST /v1/users |
| Change a user's profile, type, roles or role group, or deactivate or restore them | PUT /v1/users/{id} |
| Send a password reset email | POST /v1/users/passwordreset |
POST /v1/users/passwordreset needs no authentication: send the org domain and the user's email, and Kustomer emails a link for setting a new password. Reading users needs a user read role; inviting and updating other users needs an admin user role. GET /v1/users is paginated with page and pageSize (up to 500). To list the teams a user is on, use GET /v1/users/{id}/teams.
Path parameters
Comma-separated ObjectIds for the users to retrieve.
"582922c07c7f551a00b5b73a,582922c07c7f551a00b5b73b"Responses
OK