> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # List users ## OpenAPI ````yaml /api-reference/openapi.en.yaml get /users openapi: 3.0.3 info: title: Connecta DESK Public API version: 1.0.0 description: >- Public API of Connecta DESK, available at `/api/v1`. Access uses a token generated in the tokens module. Each token has permissions per **module × method**, and every list read is paginated. ## Authentication ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` The token belongs to a **company**, not to a user. The company used is always the token's company, so sending `companyId` in the body has no effect. A missing, invalid, revoked or expired token gets the same `401` response. ## Order of checks 1. **token** → `401` 2. **active company** → `403` 3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply to on-premise) 4. **company rate limit** → `429` 5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE` ## User ids Every user id in the API is the user's id **in this company**, the same one `GET /users` returns. This applies to what the API returns (`user.id`, `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`, `userIds`, `assignedToUserId` and the `{id}` in user routes). The same person can work in several companies, with a different name and profile in each one, and has a different id in each company. An id that does not belong to this company returns `404`, with the same message as an id that does not exist. ## Pagination Every list `GET` is paginated. The `meta` contains only `page`, `perPage` and `hasMore`, without the total number of records. To go through everything, keep advancing `page` while `hasMore` is `true`. ## Idempotency Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you repeat the call with the same key and the same body, you get the stored response (with `Idempotent-Replay: true`). With the same key and a different body, the response is `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Production security: - apiToken: [] tags: - name: contacts description: Contact records, extra fields and marketing source. - name: tickets x-displayName: Tickets description: Opening, transferring, closing and wrap-up of tickets. - name: messages description: Asynchronous sending and reading of messages. - name: tags description: Tags and their link to tickets. - name: queues description: Service queues and their agents. - name: wrapups description: Wrap-up types. - name: users description: Agents and administrators. - name: schedules description: Scheduled messages. - name: quick-messages description: Quick replies. - name: campaigns description: Bulk sending. - name: crm description: Boards, stages, cards and metrics. - name: channels description: Channels (read only). - name: reports description: Reports and dashboards. - name: products description: Product catalog, categories and sales performance. - name: custom-fields description: Custom fields for contacts and cards, plus company-wide global variables. - name: profiles description: Company permission profiles (read only). - name: webchat description: >- Native webchat from your own system: open a visitor session, send and read messages. The token needs the `webchat` scope (GET and POST). paths: /users: get: tags: - users summary: List users parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - name: search in: query description: Searches by name or email. schema: type: string example: gabriel - name: profileId in: query description: Filters by permission profile. Use the `id` from `GET /profiles`. schema: type: integer example: 21 - name: filterStatus in: query description: >- Filters by user status. `pending` means the invitation has not been accepted yet. schema: type: string enum: - active - inactive - pending - name: filterOnline in: query description: >- Filters users by presence. Use `online` for those connected right now or `offline` for those who are disconnected. schema: type: string enum: - online - offline responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/PageMeta' components: parameters: page: name: page in: query description: Page number, starting at 1. An invalid value is treated as 1. schema: type: integer minimum: 1 default: 1 example: 1 perPage: name: perPage in: query description: >- Number of items per page. The maximum depends on the environment (default 100). schema: type: integer minimum: 1 maximum: 100 default: 20 example: 50 schemas: User: type: object description: >- User from the **company's** point of view. The `id` is the user's id in this company, and the `email` belongs to the person's account. Name, profile, activation, presence and ticket limit are set per company, so the same user can have different values in each company. Super admin accounts never appear. properties: id: type: integer description: >- User id in this company. The same person has a different id in each company they work in. email: type: string example: marina@exemplo.com.br name: type: string nullable: true description: Display name in this company. profile: type: object nullable: true description: >- Permission profile of this person in this company. What each profile allows is in `GET /profiles`. It is `null` for the company owner (`isOwner: true`), who has access to everything and does not depend on a profile. properties: id: type: integer description: Profile id, the same as in `GET /profiles`. example: 21 name: type: string example: Atendente isOwner: type: boolean description: >- `true` for the company owner. The owner has access to everything, and the profile does not apply. active: type: boolean description: Access is active in this company. online: type: boolean approved: type: boolean description: '`false` when the invitation was sent and has not been accepted yet.' lastLogin: type: string format: date-time nullable: true maxOpenTickets: type: integer nullable: true example: 5 queues: type: array items: type: object properties: id: type: integer name: type: string description: Display name. example: - 7 createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 3 email: gabriel@exemplo.com.br name: Gabriel Goulart profile: id: 20 name: Admin isOwner: false active: true online: true approved: true maxOpenTickets: 15 lastLogin: '2026-08-19T08:12:00.000Z' queues: - id: 13 name: Comercial createdAt: '2026-01-08T12:00:00.000Z' updatedAt: '2026-08-19T08:30:00.000Z' PageMeta: type: object required: - page - perPage - hasMore properties: page: type: integer example: 1 perPage: type: integer example: 20 hasMore: type: boolean description: Whether there are more records beyond this page. example: true example: page: 1 perPage: 20 hasMore: true securitySchemes: apiToken: type: http scheme: bearer description: API token in the `sk_live_…` format. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.