> ## Documentation Index > Fetch the complete documentation index at: https://docs.pland.app/llms.txt > Use this file to discover all available pages before exploring further. # List Users > List all users in the system with optional filtering, pagination, and sorting capabilities. Supports advanced filtering by name, employment, status, tags, time availability, and more. ## OpenAPI ````yaml GET /users/ openapi: 3.0.0 info: title: PlanD API description: PlanD Public API version: '2' servers: - url: http:localhost:3000/v2 description: Local Server - url: https://beta-api.pland.app/v2 description: Sandbox Server - url: https://cloud-api.pland.app/v2 description: Production Server security: [] tags: - name: Absences description: >- Absence management endpoints for creating, updating, and managing user absences - name: Activity Types description: Activity type management operations - name: API Keys description: API key management operations for programmatic access to the API - name: Assignments description: Assignment management operations - name: Chat (Legacy) description: >- Legacy chat operations using Stream Chat service (deprecated - use Entity Chat v2 instead) - name: Client description: Unauthenticated client-facing operations - name: Company description: Company information and settings management operations - name: Complaints description: Customer complaint and ticket management operations - name: Contacts description: Contact person management operations - name: Customers description: Customer management operations - name: Customer Objects description: >- Customer object management operations - locations and buildings where services are performed - name: Documents description: >- Document management operations for uploading, retrieving, and managing files - name: Logbuch description: >- Operations for sending, retrieving, updating, and deleting Logbuch in entity chats. - name: Push Notifications description: Operations for listing, reading, and deleting user notifications. - name: Equipment description: Equipment management operations - name: Equipment Types description: Equipment type management operations - name: Assignment Confirmations description: Assignment confirmation management operations - name: Credit description: >- Credit note management operations for creating and handling credit documents - name: Invoice description: >- Invoice management operations for creating, managing, and processing customer invoices - name: Invoice Reminders description: >- Invoice reminder management operations for creating and handling payment reminder documents - name: Invoice Reminder Templates description: >- Invoice reminder template management operations for creating and handling reminder document templates - name: Invoice Storno description: Invoice storno (cancellation) document management operations - name: Invoice Templates description: >- Invoice template management operations for creating and handling invoice document templates - name: Offers description: Offer management operations - name: ServiceReport description: >- Service report management operations for creating and handling service documentation - name: Holiday description: Holidays management - name: Implementation description: User implementation progress tracking and onboarding management - name: Jobs description: >- Endpoints for managing jobs, including creation, listing, updating, and job-specific actions. - name: Material Orders description: Operations for listing, viewing, updating, and managing material orders. - name: Notifications description: User notification management operations - name: Payment Methods description: >- Payment method management operations for configuring available payment options - name: Payment Terms description: Operations for managing payment terms - name: Payments description: Payment management operations - name: Articles description: >- Operations for creating, listing, viewing, updating, and deleting articles. - name: Suppliers description: Supplier management operations - name: Service Products description: >- Operations for creating, listing, viewing, updating, and deleting service products. - name: Quality Control description: Quality control and assessment management operations - name: Pay Types description: Pay type management operations for salary and absence types - name: Salary description: >- Salary management operations for tracking and managing employee compensation - name: Surcharges description: Surcharge management operations for pay types and salary calculations - name: Search description: Search for entities in PlanD - name: Signing description: Endpoints for creating and listing signings (digital signatures). - name: Tasks description: Task management operations - name: Task Types description: Task type management operations - name: Tax Rates description: >- Tax rate management operations for handling VAT, zero rates, exemptions, and reverse charge scenarios - name: Time Tracking description: >- Time tracking management endpoints for recording, monitoring, and managing work time entries - name: Assets description: Asset URL management operations for secure access to uploaded files - name: Upload description: >- CSV and file uploads for various entities (articles, material, users, customers, objects, contacts, equipment, images) - name: Users description: >- User management endpoints for creating, updating, and managing system users - name: Authentication description: User authentication and password management operations - name: Banking Transactions description: Banking transaction management operations - name: Webhooks - name: SMS description: Endpoints for SMS status updates and link tracking. paths: /users/: get: tags: - Users summary: List users description: >- List all users in the system with optional filtering, pagination, and sorting capabilities. Supports advanced filtering by name, employment, status, tags, time availability, and more. operationId: listUsers parameters: - name: limit in: query description: Maximum number of users to return required: false schema: type: integer default: 100 maximum: 1000 minimum: 1 - name: offset in: query description: Number of users to skip for pagination required: false schema: type: integer default: 0 minimum: 0 - name: sort in: query description: Sort order (e.g., name:1, status.createdAt:-1) required: false schema: type: string - name: name in: query required: false schema: $ref: '#/components/schemas/FilterName' - name: username in: query required: false schema: $ref: '#/components/schemas/FilterUserName' - name: status in: query required: false schema: $ref: '#/components/schemas/FilterStatus' - name: employment in: query required: false schema: $ref: '#/components/schemas/FilterEmployment' - name: ids in: query required: false schema: $ref: '#/components/schemas/FilterIds' - name: excludeIds in: query required: false schema: $ref: '#/components/schemas/FilterExcludeIds' - name: tags in: query required: false schema: $ref: '#/components/schemas/FilterTags' - name: activityTypeId in: query required: false schema: $ref: '#/components/schemas/FilterActivityTypeId' - name: workedOnObjects in: query required: false schema: $ref: '#/components/schemas/FilterWorkedOnObjects' - name: worksOnObject in: query required: false schema: $ref: '#/components/schemas/FilterWorksOnObject' - name: currentlyWorking in: query required: false schema: $ref: '#/components/schemas/FilterUsersCurrentlyWorking' - name: basedOnObjectManager in: query required: false schema: $ref: '#/components/schemas/FilterUsersBasedOnObjectManager' responses: '200': description: List of users content: application/json: schema: type: array items: $ref: '#/components/schemas/User' '401': description: Unauthorized - Authentication required '403': description: Forbidden - Insufficient permissions '500': description: Internal server error security: - API-Key: [] - Bearer-Auth: [] components: schemas: FilterName: description: Filter by name (partial match, supports full name or number) type: string x-internal: true FilterUserName: description: Filter by user name (full name or number) type: string x-internal: true FilterStatus: description: Filter by status (single value or comma-separated list) type: string x-internal: true FilterEmployment: description: Filter by employment type (can be a single value or array) oneOf: - type: string - type: array items: type: string x-internal: true FilterIds: description: Filter by IDs (array of objectIds) type: array items: type: string format: objectid x-internal: true FilterExcludeIds: title: Exclude IDs Filter description: Filter to exclude specific IDs from search results type: array items: type: string format: objectId FilterTags: description: Filter by tags type: array items: type: string x-internal: true FilterActivityTypeId: title: Filter for Activity Type ID description: >- Filter to search jobs by activity type IDs. It can handle multiple activity type IDs and also includes checks for assignments, jobs, and salaries. type: array items: description: Activity Type ID to filter by type: string format: objectId x-internal: true FilterWorkedOnObjects: description: Filter by worked on object IDs type: array items: type: string format: objectid x-internal: true FilterWorksOnObject: title: Filter Works On Object description: Filter users based on the objects they work on type: array items: type: string format: objectId FilterUsersCurrentlyWorking: title: Filter for Users Currently Working description: Filter to search for users who are currently working on active jobs. type: boolean x-internal: true FilterUsersBasedOnObjectManager: title: Filter Users Based on Object Manager description: Filter users based on the object managers they have access to type: array items: type: string format: objectId User: title: User description: >- A system user representing an employee or team member. Inherits common entity fields and includes personal information, contact details, contract information, and system access settings. type: object allOf: - $ref: '#/components/schemas/ChatableEntityModel' - properties: id: description: Login ID type: number format: int32 example: '36920' general: $ref: '#/components/schemas/UserGeneralStruct' access: $ref: '#/components/schemas/UserAccess' contract: $ref: '#/components/schemas/ContractStruct' contact: $ref: '#/components/schemas/ContactStruct' address: $ref: '#/components/schemas/AddressStruct' accessGroupId: description: >- Access group ID defining user permissions and role within the system type: string example: service totalTargetHours: description: Total target working hours per week for the user type: number format: float example: 40 jobs: description: Associated jobs and assignments for the user type: array items: type: object setUpDone: description: Whether initial user setup has been completed type: boolean example: true location: $ref: '#/components/schemas/LocationStruct' activityTypeIds: description: >- List of activity type IDs the user is qualified or assigned to perform type: array items: type: string example: - cleaning - maintenance - inspection implementation: $ref: '#/components/schemas/ImplementationStruct' workedOnObjectIds: description: Array of customer object IDs the user has worked on type: array items: type: string format: objectid example: - 507f1f77bcf86cd799439011 - 507f191e810c19729de860ea tags: description: Tags for categorizing and filtering users type: array items: type: string example: - full-time - certified - team-lead nullable: true analytics: $ref: '#/components/schemas/UserAnalyticsStruct' type: object ChatableEntityModel: title: Chatable Entity Model description: Base class for all entities that can have a chat associated with them. type: object allOf: - $ref: '#/components/schemas/Entity' - properties: chatId: description: ID of the chat associated with this entity type: string format: objectid nullable: true type: object UserGeneralStruct: title: User General Information description: General personal information and profile data for a user properties: firstName: description: First name of the user type: string example: John lastName: description: Last name of the user type: string example: Doe sex: description: Gender/sex of the user type: string enum: - male - female - divers example: male birthDate: description: The birthday of the user dd.mm.yyyy format type: string pattern: ^\d{2}\.\d{2}\.\d{4}$ example: 15.08.1990 language: description: Preferred language code for the user interface type: string example: de insuranceNumber: description: Social insurance number type: string example: '12345678901' deviceToken: description: Mobile device push notification token type: string example: dGhpcyBpcyBhIHRva2VuIGV4YW1wbGU= webPushToken: description: Web browser push notification token type: string example: BKP4z... nullable: true profileImage: description: URL or identifier for user profile image type: string example: https://example.com/profiles/user123.jpg nullable: true description: description: Free text description or notes about the user type: string example: Team lead with 5 years experience nullable: true lastNpsScoreSend: description: Last time NPS score survey was sent to user type: string format: date-time nullable: true badges: description: Achievement badges earned by the user type: array items: type: object example: - type: experience level: senior nullable: true myTutorialUsername: description: Username for the MyTutorial platform type: string example: mytutorial_user123 nullable: true type: object UserAccess: title: User Access Credentials description: >- User authentication and access control information including login credentials, permissions, and security settings properties: dashboardAccess: description: Whether the user has access to dashboard features type: boolean example: true password: description: >- Hashed password for user authentication (never returned in API responses for security) type: string format: password writeOnly: true webAccess: description: Web access permission level or status type: string example: '1' token: description: Authentication token for API access (security-sensitive) type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 email: description: User email address used for login and communication type: string format: email example: user@company.com loginTries: description: Number of failed login attempts (used for account security) type: integer minimum: 0 example: 0 passwordChangeToken: description: Token used for password reset functionality type: string example: reset-token-12345 nullable: true passwordChangeDate: description: Date when password was last changed type: string format: date-time example: '2023-12-01T10:30:00Z' nullable: true type: object ContractStruct: title: Employment Contract description: >- Employment contract information including dates, salary, working hours, and employment terms properties: startDate: description: Contract start date type: string format: date-time example: '2023-01-01T00:00:00Z' endDate: description: Contract end date (null for indefinite contracts) type: string format: date-time example: '2024-12-31T23:59:59Z' nullable: true department: description: Department assignment (deprecated, use accessGroupId instead) type: string example: service deprecated: true salary: description: >- Salary amount (hourly rate or monthly salary depending on salary type) type: number format: float example: 15.5 salaryType: description: Type of salary calculation type: string enum: - hourly - monthly - '450' example: hourly employment: description: Employment type classification type: string example: full-time payment: description: Payment method or category type: string example: direct-deposit dailyWorkingHours: description: Daily working hours configuration type: object payTypeId: description: Reference to pay type configuration type: string format: objectid nullable: true vacationDays: description: Number of vacation days per year type: integer example: 30 remainingLeave: description: Remaining leave days from previous periods type: array items: $ref: '#/components/schemas/RemainingLeaveStruct' allowedToTrackDrivingTime: description: Whether employee is allowed to track driving time type: boolean example: true type: object ContactStruct: description: >- Contact information structure containing phone numbers, email, SMS details, and website properties: telephone: description: Primary telephone number type: string example: +1-555-123-4567 mobile: description: Mobile phone number type: string example: +1-555-987-6543 email: description: Email address type: string format: email example: contact@company.com sms: description: SMS contact number type: string example: +1-555-111-2222 smsCount: description: Number of SMS messages sent type: integer example: 5 smsChatCount: description: Number of SMS chat messages type: integer example: 12 smsSendDate: description: Date when last SMS was sent type: string format: date-time example: '2024-01-15T10:30:00Z' smsSendBy: description: User ID who sent the SMS type: string example: user123 website: description: Company website URL type: string format: uri example: https://www.company.com lastSMSStatus: description: Status of the last SMS sent type: string example: delivered secondSmsSendDate: description: Date when second SMS was sent type: string format: date-time example: '2024-01-16T14:45:00Z' type: object AddressStruct: description: Address properties: street: description: Street address type: string zip: description: ZIP/postal code type: string city: description: City type: string country: description: Country type: string co: description: Care of (c/o) type: string state: description: State/province type: string type: object LocationStruct: title: GPS Location description: >- GPS coordinates and location information used for time tracking and object positioning properties: latitude: description: Latitude coordinate in decimal degrees type: number format: double maximum: 90 minimum: -90 example: 48.8566 longitude: description: Longitude coordinate in decimal degrees type: number format: double maximum: 180 minimum: -180 example: 2.3522 location: description: >- GeoJSON representation of the location for MongoDB geospatial queries type: object example: type: Point coordinates: - 2.3522 - 48.8566 type: object ImplementationStruct: title: User Implementation Status description: Tracks user onboarding progress and system integration status properties: hasJob: description: Whether the user has been assigned to at least one job type: boolean example: true hasTimeTracking: description: Whether the user has started using time tracking functionality type: boolean example: true isSuccessfullyImplemented: description: >- Whether the user has completed the full implementation/onboarding process type: boolean example: false lastTimeActive: description: Timestamp of the user's last activity in the system type: string format: date-time example: '2023-12-01T14:30:00Z' nullable: true type: object UserAnalyticsStruct: title: User Analytics Data description: Analytics and performance tracking information for users properties: createdProfile: description: Timestamp when the user profile was created or completed type: string format: date-time example: '2023-01-15T09:00:00Z' nullable: true type: object Entity: title: Entity description: >- Base class for all entities in the system, providing common properties and methods. properties: _id: description: Unique identifier of the entity type: string format: objectid number: description: Unique number of the entity, used for identification type: integer companyId: description: The ID of the company this entity belongs to type: string format: objectid x-internal: true status: $ref: '#/components/schemas/StatusStruct' type: object RemainingLeaveStruct: title: Remaining Leave Days description: >- Tracks remaining vacation days that can be carried over from previous years properties: year: description: The year for which these remaining leave days apply type: integer maximum: 2050 minimum: 2020 example: 2023 days: description: Number of remaining leave days available to be used type: integer minimum: 0 example: 5 type: object StatusStruct: description: Entity Status information properties: status: description: Current status type: integer createdAt: description: Creation timestamp type: string format: date-time createdBy: description: User who created this supplier type: string format: objectid lastModifiedAt: description: Last modification timestamp type: string format: date-time lastModifiedBy: description: User who last modified this supplier type: string format: objectid type: object securitySchemes: API-Key: type: apiKey name: x-API-Key in: header Bearer-Auth: type: http bearerFormat: JWT scheme: bearer ````