# Users List

**GET** `/v1/users`

Lists platform users with pagination, text search, role filtering, date ranges, and custom attributes.

### Access Control

Requires an admin secret key (`admin: 1`) or an authenticated account owner.

---

### Query Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| `page` | `integer` | Required | Page number for pagination (starts from 1). |
| `per_page` | `integer` | Optional | Number of user records per page (between 1 and 100). Default is 30. |
| `search_key` | `string` | Optional | Searches case-insensitively across `first_name`, `last_name`, `email`, and `mobile`. |
| `type` | `string` | Optional | Filter by role types stored in `users.type`. Supports a single type or comma-separated list of types (e.g. `buyer,seller`, `customer`). Returns users possessing any of the specified roles. |
| `user_type` | `string` | Optional | Filter by user account ownership classification: <br>• `customer`: Users with the customer role who do not own an active account.<br>• `account`: Users who own an active account. |
| `created_from` | `string` | Optional | Filter users registered on or after this ISO-8601 UTC timestamp.<br>Example: `2024-01-01T00:00:00Z` |
| `created_to` | `string` | Optional | Filter users registered on or before this ISO-8601 UTC timestamp.<br>Example: `2024-12-31T23:59:59Z` |
| `sort` | `string` | Optional | Sort order by creation timestamp: `newest_first` (default) or `oldest_first`. |
| `ids` | `string` | Optional | Comma-separated list of user unique IDs (UUIDs) to fetch specific users.<br>Example: `692ee113-310b-4e66-b5b5-33796f9616e3,824ee113-420c-4e66-a4b4-44796f9616e4` |
| `status` | `string` | Optional | Filter by user status:<br>• `1`: Active users (`USER_STATUS_ACTIVE`)<br>• `2`: Inactive users (`USER_STATUS_INACTIVE`)<br>• `1,2`: Include both active and inactive users.<br>Defaults to `1` (active only) if omitted. |
| `include_attributes` | `string` | Optional | Set to `true` or `1` to populate custom profile attributes under each user object in the response. |

---

### Response Fields

**total_records** Total count of users matching the filter criteria.  
**page** Current page number.  
**users** Array of user objects matching the query:  
- **id** Unique identifier (UUID) of the user.  
- **first_name** First name of the user.  
- **last_name** Last name of the user.  
- **email** Email address.  
- **profile_pic** Profile picture URL.  
- **email_verified** Boolean indicating whether email is verified.  
- **email_bounced** Boolean indicating whether emails have bounced.  
- **email_complained** Boolean indicating spam complaints.  
- **mobile** Mobile phone number without dial code.  
- **dial_code** Country dial code without the `+` sign.  
- **type** Array of assigned user roles (e.g. `["buyer", "customer"]`).  
- **metadata** Custom JSON metadata attached to the user.  
- **locale** User's preferred language code.  
- **status** Account status code (`1` for active, `2` for inactive).  
- **otp_enabled** Boolean indicating if two-factor OTP login is enabled.  
- **following_count** Total count of accounts followed by this user.  
- **is_following_user** Boolean indicating if the requesting user follows this user.  
- **attributes** *(optional)* Array of custom user profile attribute values (included when `include_attributes=true`).  
- **created_at** Unix timestamp when the user registered.  
- **updated_at** Unix timestamp when the user profile was last updated.  
- **lastlogin_at** Unix timestamp of the user's most recent login session.