DealHub User API
Retrieve DealHub users by login or by DealHub user id, list users, and create or update users in bulk through the v1 and v2 user provisioning endpoints.
OpenAPI Specification
openapi: 3.0.3
info:
title: User API
description: 'This API provides a set of services for managing user information within the DealHub platform. It allows for
system-to-system integration to retrieve, create, and update user data.
All requests require a secret Bearer Token in the `Authorization` header, which is generated by a CPQ administrator.'
version: 1.0.0
servers:
- url: https://api.dealhub.io
description: The base URL for your DealHub instance.
variables:
your-dealhub-instance:
default: app
description: Your specific DealHub instance name (e.g., 'app', 'service-eu1').
security:
- bearerAuth: []
tags:
- name: User Management
description: Endpoints for retrieving and managing user data.
paths:
/api/v1/user/login/{login}:
get:
tags:
- User Management
summary: Get User by Login
description: Retrieves a single user's details based on their login name. Fields with null values will not be included
in the response.
operationId: getUserByLogin
parameters:
- name: login
in: path
required: true
schema:
type: string
maxLength: 100
description: The login name of the user.
responses:
'200':
description: Success. Returns the user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
getUserByLoginExample:
summary: Successful user retrieval
value:
login: john@my_domain.com
id: '786865656908'
email: john@my_domain.com
name: John Smith
position: Sales
phone: 09-445556
mobile: 023-6654464
fax: 09-756576
company: My Domain
street: Harokmin 26
city: Holon
state: Center
country: Israel
postal_code: '563733'
is_active: true
'400':
description: Bad Request. The user could not be found.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v1/user/id/{id}:
get:
tags:
- User Management
summary: Get User by ID
description: Retrieves a single user's details based on their DealHub user ID. Fields with null values will not be included
in the response.
operationId: getUserById
parameters:
- name: id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique DealHub ID of the user.
responses:
'200':
description: Success. Returns the user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
getUserByIdExample:
summary: Successful user retrieval
value:
login: john@my_domain.com
id: '786865656908'
email: john@my_domain.com
name: John Smith
position: Sales
phone: 09-445556
mobile: 023-6654464
fax: 09-756576
company: My Domain
street: Harokmin 26
city: Holon
state: Center
country: Israel
postal_code: '563733'
is_active: true
'400':
description: Bad Request. The user could not be found.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v1/users:
get:
tags:
- User Management
summary: Get a List of Users
description: Retrieves a list of users. If no parameters are provided, it will retrieve all users. Fields with null
values will not be included in the response.
operationId: getUsers
parameters:
- name: status
in: query
schema:
type: string
enum:
- active
- inactive
description: Filter users by their active or inactive status.
responses:
'200':
description: Success. Returns an array of user objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
examples:
getUsersExample:
summary: A list of active users
value:
- 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
phone: 09-445556
mobile: 023-6654464
fax: 09-756576
company: My Domain
street: Harokmin 26
city: Holon
state: Center
country: Israel
postal_code: '563733'
user_manager_login: daniel@my_domain.com
is_active: true
'403':
description: Forbidden. Invalid or missing authentication token.
put:
tags:
- User Management
summary: Update Users (v1)
description: Updates one or more existing users in DealHub. This operation identifies users by their `login`, which
is an immutable field.
operationId: updateUsersV1
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
users:
type: array
description: A list of users to be updated.
items:
$ref: '#/components/schemas/UserUpdateV1'
examples:
updateUsersV1Example:
summary: Update a single user's details
value:
users:
- login: daniel@my_domain.com
email: daniel_a@my_domain.com
name: Daniel Smith
position: CCS
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: royll
is_active: true
responses:
'200':
description: Success. The response may contain a list of errors for users that could not be updated.
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdateErrorResponse'
examples:
updateUserErrorExample:
summary: Response with errors for specific users
value:
errors:
- login: daniel@my_domain.com
message: <SPECIFIC ERROR DETAILS>
- login: john@my_domain.com
message: <SPECIFIC ERROR DETAILS>
'400':
description: Bad Request. The request payload is invalid.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v2/users:
put:
tags:
- User Management
summary: Create or Update Users (v2)
description: Creates new users or updates existing ones. The operation uses the `login` field to identify existing users.
operationId: createOrUpdateUsersV2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/UserUpdateV2'
examples:
createOrUpdateUsersV2Example:
summary: Create or update a single user
value:
users:
- login: daniel@my_domain.com
email: daniel_a@my_domain.com
name: Daniel Smith
position: CCS
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: royll
is_active: true
responses:
'200':
description: Success. The operation was completed.
'400':
description: Bad Request. The request payload is invalid.
'403':
description: Forbidden. Invalid or missing authentication token.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A secret token generated by a CPQ administrator.
schemas:
User:
type: object
properties:
login:
type: string
maxLength: 100
description: Login of the user.
id:
type: string
maxLength: 16
description: DealHub user ID.
email:
type: string
format: email
maxLength: 100
description: Primary email of the user.
name:
type: string
maxLength: 300
description: User's full name.
position:
type: string
maxLength: 300
description: The role of the user in the organization (job title).
business_title:
type: string
description: Business title of the user in the CRM organization.
phone:
type: string
maxLength: 50
description: User's phone number.
mobile:
type: string
maxLength: 100
description: User's mobile phone number.
fax:
type: string
maxLength: 100
description: User's fax number.
company:
type: string
maxLength: 100
description: User's company name.
street:
type: string
maxLength: 128
description: Street name.
city:
type: string
maxLength: 32
description: City name.
state:
type: string
maxLength: 32
description: State name.
country:
type: string
maxLength: 32
description: Country name.
postal_code:
type: string
maxLength: 16
description: Postal code.
user_manager_login:
type: string
maxLength: 100
description: Login of the user's manager.
is_active:
type: boolean
description: Flag indicating if the user is active.
UserUpdateV1:
type: object
properties:
login:
type: string
maxLength: 100
description: Login of the user. An immutable field used as an identifier.
email:
type: string
format: email
maxLength: 100
description: Primary email of the user.
name:
type: string
maxLength: 300
description: User's full name.
is_active:
type: boolean
description: The flag that specifies if a user should be marked as active in the CPQ system. When a user is inactive,
he/she cannot access CPQ.
position:
type: string
maxLength: 300
description: The role of the user in the organization (job title).
phone:
type: string
maxLength: 50
description: User's phone number.
mobile:
type: string
maxLength: 100
description: User's mobile phone number.
fax:
type: string
maxLength: 100
description: User's fax number.
company:
type: string
maxLength: 100
description: User's company name.
street:
type: string
maxLength: 128
description: Street name.
city:
type: string
maxLength: 32
description: City name.
state:
type: string
maxLength: 32
description: State name.
country:
type: string
maxLength: 32
description: Country name.
postal_code:
type: string
maxLength: 16
description: Postal code.
user_manager_login:
type: string
maxLength: 100
description: Login of the user's manager.
required:
- login
- email
- name
- is_active
UserUpdateV2:
type: object
properties:
login:
type: string
maxLength: 90
description: Login of the user. An immutable field used as an identifier.
email:
type: string
format: email
maxLength: 100
description: Primary email of the user.
name:
type: string
maxLength: 300
description: User's full name.
external_user_id:
type: string
maxLength: 200
description: CRM user ID (ID of the employee within the organization that integrates with DealHub).
is_active:
type: boolean
description: The flag that specifies if a user should be marked as active in the CPQ system. When a user is inactive,
he/she cannot access CPQ.
position:
type: string
maxLength: 300
description: The role of the user in the organization (job title).
business_title:
type: string
description: Business title of the user in CRM organization.
phone:
type: string
maxLength: 50
description: User's phone number.
mobile:
type: string
maxLength: 100
description: User's mobile phone number.
fax:
type: string
maxLength: 100
description: User's fax number.
company:
type: string
maxLength: 100
description: User's company name.
street:
type: string
maxLength: 128
description: Street name.
city:
type: string
maxLength: 32
description: City name.
state:
type: string
maxLength: 32
description: State name.
country:
type: string
maxLength: 32
description: Country name.
postal_code:
type: string
maxLength: 16
description: Postal code.
user_manager_login:
type: string
maxLength: 100
description: Login of the user's manager.
required:
- login
- email
- name
- external_user_id
- is_active
UserUpdateError:
type: object
properties:
login:
type: string
message:
type: string
UserUpdateErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UserUpdateError'
x-readme:
explorer-enabled: true
proxy-enabled: true