User API Overview

The User API is a set of system-to-system services that lets consuming applications retrieve, create, and update user records in DealHub CPQ. It is designed for organizations integrating DealHub with an external CRM or identity management system that need to keep user data synchronized programmatically.

Common use cases include provisioning users when they are added to the CRM, deactivating users when they leave the organization, updating profiles when user details change, and retrieving user data to support reporting or approval workflows.

Prerequisites

Before making any User API calls, ensure the following are in place. All endpoints on this page require a valid authentication token, and write operations require that the users you intend to manage already exist or are ready to be provisioned.

• DealHub Authentication Token: A CPQ administrator must generate a token in System Settings > API Settings and share it with the consuming application. For instructions, see Authentication.
• Admin access: The token must have the necessary permissions to read and write user records in DealHub CPQ.

Available Endpoints

The User API provides five endpoints organized across four guide pages. Use the table below to identify the right starting point for your use case.

📘

Prefer v2 for write operations

The Create or Update Users (v2) endpoint handles both new and existing users in a single call. For most automated sync workflows, this is the more resilient choice because it does not require the consuming system to know in advance whether a user already exists in DealHub. Use Update Users (v1) only if your integration specifically requires it.

Authentication

All User API requests use token-based authentication. Include the DealHub Authentication Token in the Authorization header of every request.

Authorization: Bearer <TOKEN_PROVIDED_BY_CPQ_ADMIN>

❗️

Keep the token secret

The authentication token is a long-lived credential that does not expire. Store it in a secrets manager or environment variable. Never include it in client-side code or source control. If the token is compromised, delete it in System Settings immediately and generate a new one.

Asynchronous Request Processing and Tracking

Some User API operations are processed asynchronously. For these requests, DealHub returns a request_id in the response body instead of an immediate result.

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

DealHub publishes a webhook event once the operation completes. The same request_id is included in that event payload, so the consuming system can match it back to the original request.

📘

Webhook setup required

To track asynchronous requests, your system must have a webhook endpoint configured to receive CPQ events. For setup instructions and a full list of available events, see How to Configure Webhooks.

Key Concepts

The login field is the permanent user identifier

The login field is immutable once a user record is created. DealHub uses it as the unique key to identify a user across all operations. Choose the login value carefully before provisioning a user for the first time, it cannot be changed after creation.

🚧

The login field must be unique across all DealHub tenants, not just within your own account. To avoid collisions, use a composite format such as USER_EMAIL@{company_name}. If you maintain both a sandbox and a production environment, append a suffix such as _sb to sandbox logins to keep them separate from production records.

Deactivate users instead of deleting them

When a user leaves the organization, set is_active to false rather than removing the record. Inactive users cannot access CPQ, but their historical quote data and records remain intact.

Populate optional fields at creation time

Fields such as position, business_title, and user_manager_login drive CPQ workflows, approval routing, and document template parameters. Sending them at creation time avoids a follow-up update call and ensures the user record is complete from the start.

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.
• Get a List of Users: Retrieve all users or filter by active or inactive status.
• 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.