Create or Update Users (v2)

Use this endpoint to create new users or update existing ones in DealHub CPQ in a single call. If a user with the given login already exists, DealHub updates their record. If no matching user is found, DealHub creates a new one. This upsert behavior makes it the recommended endpoint for automated sync workflows where the consuming system may not know in advance whether a user has already been provisioned.

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.
• The login identifier for each user: The login field is required for every user object in the request and must be globally unique across all DealHub tenants. See the callout in Step 1 for guidance on choosing a safe login format.
• The CRM user ID for each user: The external_user_id field is required in v2. Have the CRM-assigned ID available for every user you intend to create or update.

The Create or Update Workflow

Each time your integration needs to create or update one or more users, complete the following steps:

1. Build the request body as a JSON array containing one object per user you want to create or update.
2. Send the request to PUT /api/v2/users from your backend.
3. Handle the response and confirm the operation completed successfully.

Step 1: Build the Request Body

Construct a users array where each object represents one user. DealHub matches each object against existing records using the login field. Every object must include all required fields. Include any optional fields you want to set or update -- fields omitted from the request are left unchanged for existing users.

🚧

login must be globally unique across all DealHub tenants

The login field must be unique across all DealHub tenants, not just within your own account. If a user with the same login exists in a different tenant, creation will fail for that user. 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.

📘

Populate optional fields at creation time

When DealHub creates a new user, it writes the provided field values to the record at that point. Fields such as position, business_title, and user_manager_login drive CPQ workflows, approval routing, and document template parameters. Include them on the first call to avoid a follow-up update request.

Request body:

{
  "users": [
    {
      "login": "daniel@my_domain.com",
      "email": "daniel_a@my_domain.com",
      "name": "Daniel Smith",
      "external_user_id": "CRM-USER-00123",
      "is_active": true,
      "position": "CCS",
      "business_title": "Senior Account Executive",
      "phone": "09-445556",
      "mobile": "054-1010101",
      "fax": "09-4545456",
      "company": "My Domain",
      "street": "Harokmin 26",
      "city": "Holon",
      "state": "Center",
      "country": "Israel",
      "postal_code": "563733",
      "user_manager_login": "roy11"
    }
  ]
}

Required parameters:

Optional parameters:

📘

position and business_title serve different purposes

Both fields carry user title information but behave differently in DealHub. position is displayed in the CPQ UI as the user's Position and is used when defining general workflows. business_title is not shown in the CPQ UI but can be referenced in workflows and document templates via USER_BUSINESS_TITLE. Set both if your CRM stores them separately.

Step 2: Send the Request

Method: PUT

URL: /api/v2/users

Step 3: Handle the Response

A successful request returns HTTP 200 with an empty response body, confirming all users in the batch were created or updated.

📘

Verify the result with a follow-up read

To confirm a specific user was created or updated as expected, use Retrieve a User after the request completes. This is particularly useful during initial integration testing or when onboarding a large batch of users for the first time.

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.

📘

Related API Reference

The Create or Update Users (v2) API Reference page documents the endpoint used in this guide.