Get a List of Users

Use this endpoint to retrieve user records from DealHub CPQ in bulk. By default, the endpoint returns all users under your account. You can narrow the results by filtering on user status.

Common use cases include auditing which users are currently active, building a directory of all provisioned users, and identifying inactive accounts for cleanup or reporting.

Prerequisites

Before making any requests on this page, ensure the following are in place.

• DealHub Authentication Token: Include the token in the Authorization header of every request. For instructions on generating a token, see Authentication.
• Admin access: The token must have the necessary permissions to read user records in DealHub CPQ.

The Retrieval Workflow

Each time your integration needs to retrieve a list of users, complete the following steps:

1. Decide whether to filter by user status or retrieve all users.
2. Send the request from your backend with the appropriate query parameter.
3. Handle the response and process the returned list of user records.

Step 1: Decide Whether to Filter

Omitting the status parameter returns all users under the account, both active and inactive. Include status when you only need one group.

📘

When to use each option

• Omit status when building an initial sync or auditing the full user base.
• Use status=active when your workflow only needs to act on users who can currently access CPQ.
• Use status=inactive when identifying accounts to review, re-activate, or remove from downstream systems.

Step 2: Send the Request

Method: GET

URL: /api/v1/users

Example request with filter:

GET /api/v1/users?status=active

Query parameter:

Step 3: Handle the Response

A successful request returns HTTP 200 and a JSON array. Each object in the array represents one user and follows the same field structure as Retrieve a User.

[
  {
    "login": "daniel@my_domain.com",
    "id": "786865656908",
    "email": "daniel@my_domain.com",
    "name": "Daniel Agassi",
    "position": "CCS",
    "phone": "09-445556",
    "mobile": "076-6654464",
    "fax": "09-4545456",
    "company": "My Domain",
    "street": "Harokmin 26",
    "city": "Holon",
    "state": "Center",
    "country": "Israel",
    "postal_code": "563733",
    "is_active": true
  },
  {
    "login": "john@my_domain.com",
    "id": "78686565623",
    "email": "john@my_domain.com",
    "name": "John Smith",
    "position": "Sales",
    "company": "My Domain",
    "user_manager_login": "daniel@my_domain.com",
    "is_active": true
  }
]

📘

Null fields are omitted

Fields with a null value are not included in the response. If a field does not appear on a user object, its value is not set for that user. For a full description of all possible response fields, see Retrieve a User - Response fields.

🚧

Do not use this endpoint to retrieve individual users at scale

This endpoint returns the full list of user records in a single response. If your workflow needs to look up a specific user, use Get User by Login or Get User by ID instead. Fetching the full list and filtering client-side is inefficient and increases unnecessary load.

Next Steps

Now that you understand the core concepts, proceed to the practical guides:

• Retrieve a User: Get a single user record by login identifier or DealHub user ID.
• Update Users (v1): Update one or more existing user records.
• Create or Update Users (v2): Create new users or update existing ones in a single call.

📘

Related API Reference

The Get a List of Users API Reference page documents the endpoint used in this guide.