API DocsAPI Docs / GET /api/v1/users

GET /api/v1/users

Retrieve a paginated list of users, with support for advanced filtering and sorting.

Permissions

Note: Users with users.view_limited permission but not users.view_all must provide at least one character in the search parameter, or provide user_id, otherwise the API will return 0 results.

Query Parameters

*Required when user has users.view_limited permission but not users.view_all

Default sort is by created_at (newest first).

Why limited viewers search less. A user without users.view_all never sees anyone else's email, phone or verification state, so nothing they can ask for may depend on them either. Matching a search against email or phone let such a user pin someone with user_id and grow a guess one character at a time, learning the value from whether the account came back; sorting or filtering by those columns leaks the same way. For them, search matches name and username only, and the contact filters and sort keys are ignored.

What phone_status=verified means. phone_verified_at is written when a one-time code has proven control of the number: at the end of registration and on a completed password reset. It is never accepted from a request on any endpoint, and PUT /api/v1/users/{user} clears it again whenever the phone number itself changes. An account created by an operator through POST /api/v1/users is not verified: no code was ever sent.

Accounts that registered before this was recorded still read as not verified until they next reset their password. An operator can close that gap in one pass with php artisan users:backfill-phone-verification, which reports counts and writes nothing until it is given --write.

Accounts pending deletion are omitted. A user who has requested their own account deletion disappears from this listing the moment the request lands, not when the account is disposed of 14 days later. Holders of users.view_all keep seeing them, with deletion_requested_at and deletion_scheduled_at on the resource, so a support call about a pending deletion is answerable. The exclusion is derived from the viewer's permissions and is not a query parameter: a client cannot ask its way past it. See POST /api/v1/auth/delete-account.

search matching. The term and the text it is matched against are both normalized first, so an account whose name is stored with an Arabic keyboard's ي/ك is found by a search typed with the Persian ی/ک and vice versa; the same applies to hamza-bearing alefs, teh marbuta, zero-width joiners and non-joiners, the tatweel, Arabic diacritics, and Persian or Arabic-Indic digits, so a phone number typed ۰۹۱۲… finds one stored 0912…. Matching is case-insensitive and matches anywhere in the text, not only at the start. % and _ are literal characters: ?search=% returns only accounts whose text actually contains a percent sign, not every account. A term that normalizes to nothing (whitespace, a lone zero-width non-joiner) is treated as no term at all, which for a users.view_limited viewer means the listing comes back empty.

The five fields are matched as one string, so a term may span two of them in order: "ali reza" matches the account whose first name is ali and last name reza. A term over 255 characters is rejected with 422.

Response

200 OK

{
  "data": [
    {<user resource>},
    ...
  ],
  "links": {<pagination data>},
  "meta": {<pagination data>}
}

• User Resource
• Pagination Data (per page: 30)

Error Responses