Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST /v2/users

​
Description

Search for users. By default, all users of your instance that you have permission to read will be returned. Make sure to include a limit and sorting for pagination.

​
Required Permission

  • authenticated

​
Request Body

​
query
object
Pagination and sorting options.
​
offset
string
Offset for pagination (number of items to skip).
​
limit
integer
Maximum number of results to return.
​
asc
boolean
Sort in ascending order (true) or descending (false).
​
sortingColumn
string
Field to sort by. Options include:
  • USER_FIELD_NAME_USER_NAME
  • USER_FIELD_NAME_FIRST_NAME
  • USER_FIELD_NAME_LAST_NAME
  • USER_FIELD_NAME_EMAIL
  • USER_FIELD_NAME_STATE
  • USER_FIELD_NAME_CREATION_DATE
​
queries
array
Search filters to apply. Each filter narrows the results.
​
userNameQuery
object
Filter by username.
​
userName
string
Username to search for (supports wildcards).
​
method
string
Search method: TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_CONTAINS.
​
emailQuery
object
Filter by email address.
​
emailAddress
string
Email to search for.
​
method
string
Search method.
​
stateQuery
object
Filter by user state.
​
state
string
State to filter by: USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL.
​
organizationIdQuery
object
Filter by organization.
​
organizationId
string
Organization ID to filter by.

​
Response

​
details
object
Pagination details.
​
totalResult
string
Total number of users matching the query.
​
processedSequence
string
Sequence number of the query.
​
timestamp
timestamp
Timestamp of the query.
​
result
array
Array of users matching the query.
​
userId
string
Unique identifier of the user.
​
username
string
Username of the user.
​
state
string
Current state of the user.
​
loginNames
array
Possible login names for the user.
​
preferredLoginName
string
Preferred login name.
​
human
object
Human user details (if applicable).
​
profile
object
Profile information.
​
email
object
Email information.
​
phone
object
Phone information.
​
machine
object
Machine user details (if applicable).

​
Example Request

curl -X POST https://your-domain.zitadel.cloud/v2/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "limit": 50,
      "asc": true
    },
    "sortingColumn": "USER_FIELD_NAME_USER_NAME",
    "queries": [
      {
        "stateQuery": {
          "state": "USER_STATE_ACTIVE"
        }
      },
      {
        "emailQuery": {
          "emailAddress": "@example.com",
          "method": "TEXT_QUERY_METHOD_CONTAINS"
        }
      }
    ]
  }'

​
Example Response

{
  "details": {
    "totalResult": "42",
    "processedSequence": "1500",
    "timestamp": "2024-03-15T13:00:00Z"
  },
  "result": [
    {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "username": "minnie.mouse",
      "state": "USER_STATE_ACTIVE",
      "loginNames": [
        "minnie.mouse@example.com",
        "minnie.mouse@zitadel.cloud"
      ],
      "preferredLoginName": "minnie.mouse@example.com",
      "human": {
        "profile": {
          "givenName": "Minnie",
          "familyName": "Mouse",
          "displayName": "Minnie Mouse"
        },
        "email": {
          "email": "minnie.mouse@example.com",
          "isVerified": true
        }
      }
    }
  ]
}

​
Error Responses

  • 400 Bad Request - Invalid list query
  • 403 Forbidden - Insufficient permissions