Manage DealHub configuration Versions and their product catalog — retrieve, duplicate and activate versions, export playbook data, read and upload the product catalog, patch catalog items, manage the product hierarchy, and poll asynchronous request status.
openapi: 3.0.3
info:
title: Version API
description: 'This API provides a comprehensive set of services for managing versions and the associated product catalog
within the DealHub CPQ system. It allows for system-to-system integration to get, create, duplicate, activate, and manage
the content of versions.
Several operations, such as duplicating, activating, and uploading a product catalog, are asynchronous. These endpoints
return a `request_id` for tracking.
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: Version Management
description: Endpoints for retrieving, creating, and managing versions.
- name: Playbook
description: Endpoints for exporting Playbook configuration and data in JSON format, and for generating a Generate Quote
API request template based on the Playbook structure.
- name: Product Catalog
description: Endpoints for managing the product catalog within a specific version.
- name: Asynchronous Operations
description: Endpoints for tracking the status of asynchronous requests.
- name: Beta
description: New endpoints that are currently in beta.
paths:
/api/v1/version/id/{version_id}:
get:
tags:
- Version Management
summary: Get Version by ID
description: Retrieve a specific Version based on its unique DealHub ID.
operationId: getVersionById
parameters:
- name: version_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique identifier of the version.
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
examples:
getVersionExample:
summary: Successful response
value:
name: Master v1
comment: ''
status: ACTIVE
version_id: '67657'
/api/v1/version/name/{version_name}:
get:
tags:
- Version Management
summary: Get Version by Name
description: Retrieve a specific Version based on its name.
operationId: getVersionByName
parameters:
- name: version_name
in: path
required: true
schema:
type: string
maxLength: 120
description: The name of the version.
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/Version'
examples:
getVersionExample:
summary: Successful response
value:
name: Master v1
comment: ''
status: ACTIVE
version_id: '67657'
/api/v1/versions:
get:
tags:
- Version Management
summary: Get a List of Versions
description: Retrieve a list of Versions, with an option to filter by status. If no parameters are provided, it returns
all versions.
operationId: getVersions
parameters:
- name: status
in: query
schema:
type: string
enum:
- DRAFT
- ACTIVE
- DEACTIVATED
description: Search for Version(s) based on status.
responses:
'200':
description: Success. Returns a list of version objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Version'
examples:
getVersionsExample:
summary: Example list of versions
value:
- name: v3a
comment: ''
status: DEACTIVATED
version_id: 068DoObdli5GuF14
- name: msd6
comment: ''
status: DEACTIVATED
version_id: 0AjX3aABgLN9f8uG
/api/v1/version/duplicate:
post:
tags:
- Version Management
summary: Duplicate a Version
description: Asynchronously creates a new Version entity based on an existing one. This operation returns a `request_id`
for tracking.
operationId: duplicateVersion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateVersionRequest'
examples:
duplicateVersionExample:
summary: Duplicate a version to a new instance
value:
version_id: '765379899'
new_version_name: New Version
comment: Adding more BroadBand services
to_account_instance: Account abc
responses:
'200':
description: Success. The duplication process has started.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncResponse'
examples:
asyncResponseExample:
summary: Successful response
value:
request_id: 4D114DAD97
/api/v1/version/activate:
post:
tags:
- Version Management
summary: Activate a Version
description: Asynchronously activates a `DRAFT` Version. This operation returns a `request_id` for tracking.
operationId: activateVersion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateVersionRequest'
examples:
activateVersionExample:
summary: Request to activate a version
value:
version_id: '765379899'
responses:
'200':
description: Success. The activation process has started.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncResponse'
examples:
asyncResponseExample:
summary: Successful response
value:
request_id: 4D114DAD97
/api/version/{versionName}/playbook/{playbookId}/export:
get:
tags:
- Playbook
summary: Get Playbook Data
description: 'Retrieves the details of the requested Playbook in a specific version, exporting the Playbook configuration
and data in JSON format.
Date-type attributes and playbook questions are returned in the format `yyyy-mm-dd hh:mm:ss`.
The result might differ, depending on the requested features.'
operationId: exportPlaybookData
parameters:
- name: versionName
in: path
required: true
schema:
type: string
description: Version name.
- name: playbookId
in: path
required: true
schema:
type: string
description: Playbook name (not the Playbook display name).
responses:
'200':
description: Success. Returns the Playbook details if a valid identifier is provided.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaybookExportResponse'
examples:
exportPlaybookDataExample:
summary: Successful response
value:
playbook_metadata:
name: API
display: API
document_type:
- PDF
geo_factors_settings: true
present_proposal_summary: true
enable_partner_support: false
sync_document_settings:
enabled: RULE_BASED
based_on: '[QG1.name] = [QG2.question_1]'
sync_product_settings:
enabled: NEVER
based_on: null
playbook_data:
- group_id: QG1
group_name: QG1
group_type: QUESTIONS_GROUP
group_external_object: ''
question_data:
- question_id: name
question: name
question_type: Text list
answers: 1;2
default_answer: '1'
- question_id: address
question: address
question_type: Text list
answers: 1;2;3
default_answer: '1'
- group_id: QG2
group_name: QG2
group_type: REPEATABLE_GROUP
group_external_object: ''
question_data:
- question_id: question_1
question: question 1
question_type: Text list
answers: answer
default_answer: answer
- question_id: question_2
question: question 2
question_type: Text list
answers: answer 2
default_answer: answer 2
/api/version/{versionId}/playbook/{playbookId}/generate-quote-template:
get:
tags:
- Playbook
summary: Get Generate Quote Template
description: 'Returns a preformatted JSON template for API quote generation based on the Playbook structure. Use this
template as the starting point for Generate Quote API requests.
Date-type attributes and playbook questions are returned in the format `yyyy-mm-dd hh:mm:ss`.
Template generation rules:
- The template includes all required API fields.
- The template includes default values if they exist. Otherwise, it uses the first available answer.
- The template excludes calculated questions.'
operationId: getGenerateQuoteTemplate
parameters:
- name: versionId
in: path
required: true
schema:
type: string
description: Version name.
- name: playbookId
in: path
required: true
schema:
type: string
description: Playbook name (not the Playbook display name).
responses:
'200':
description: Success. Returns the Generate Quote template JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateQuoteTemplateResponse'
examples:
generateQuoteTemplateExample:
summary: Template JSON structure
value:
external_opportunity_id: ''
request_action: draft
line_item_details: basic
playbook: <playbook_name>
quote_name: ''
dealroom_publish_name: ''
total_sales_discount: 0
expiration_date: ''
document_type: PDF
timezone_offset: 0
partner_program:
- partner_level_name: ''
program_name: ''
quote_data:
- group_id: <group_id>
questions:
- <question_id_1>: ''
<question_id_2>: ''
line_items:
- sku: <SKU>
item_name: ''
bundle_ref_sku: ''
bundle_ref_id: 0
list_price: 0
net_price_per_unit: 0
net_price: 0
msrp: 0
msrp_discount: 0
sales_discount: 0
total_discount: 0
product_factors:
Quantity: 1
Duration: 1
attributes:
<attribute_name_1>: ''
<attribute_name_2>: 0
<attribute_name_3>: YYYY-MM-DD
partner_program_data:
- partner_program_name: ''
partner_level_item_price: 0
partner_level_item_discount: 0
sign_externally_comment: ''
'400':
description: Bad Request. Invalid versionId.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaybookErrorResponse'
'404':
description: Playbook not found.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaybookErrorResponse'
examples:
playbookNotFoundExample:
summary: Error response
value:
error: Playbook not found
code: 404
'500':
description: Failed to generate JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/PlaybookErrorResponse'
/api/v1/version/{version_id}/products:
get:
tags:
- Product Catalog
summary: Get Products of a Version
description: 'Retrieves a paginated list of products for a specific version, returning basic product attributes and
price details.
- `DRAFT` Status: Returns the full product list.
- `ACTIVE`/`DEACTIVATED` Status: Can return either all products or only products that were new or modified compared
to the previously active version.'
operationId: getVersionProducts
parameters:
- name: version_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique identifier of the Version.
- name: offset
in: query
schema:
type: integer
minimum: 0
maximum: 10000
description: The number of products to skip for pagination.
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 1000
description: The maximum number of products to return. If the requested `limit` value exceeds the maximum allowed
limit, the system will automatically cap the result set at the maximum limit.
- name: product_option
in: query
schema:
type: string
enum:
- ALL
- MODIFIED
default: ALL
description: Specify whether to fetch all products or only new/updated products.
- name: pricing_option
in: query
schema:
type: string
enum:
- MIN
- MAX
- FIRST
default: MIN
description: For products with multiple fixed prices, specifies which price to return (Minimum, Maximum, or First
defined).
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/VersionProductsResponse'
examples:
getVersionProductsExample:
summary: Successful response
value:
info:
version_id: '76472'
version_status: ACTIVE
compared_with_version_id: '76326'
more_results_matching_the_request: true
offset: '1'
limit: '25'
products:
- sku: '56545'
name: Product A
type: PRODUCT
description: Description of product A
price:
EUR: '10'
USD: '12.5'
attributes:
- attr_x: value X
- attr_y: value Y
- sku: '56546'
name: Product B
type: PRODUCT
description: Description of product B
price:
EUR: '18'
USD: '21.5'
attributes:
- attr_x: value XX
- attr_y: value YY
- sku: 56545_b
name: Bundle X
type: BUNDLE
description: Description of bundle X
price:
EUR: '10'
attributes:
- attr_x: value XYZ
- attr_y: value YZ
bundle_items:
- '56545'
- '56546'
/api/v1/version/product_by_sku:
post:
tags:
- Product Catalog
summary: Get Products by SKU
description: 'Retrieves basic details for a specific list of products from the catalog based on their SKUs.
> 📘
> If some SKUs could not be found in a specific Version the system will return status 200, with error in the `info`
structure.'
operationId: getProductsBySku
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductsBySkuRequest'
examples:
getProductsBySkuExample:
summary: Request specific products by SKU
value:
version_id: 23687268JS5
pricing_option: MAX
sku:
- Sku-123-dvvv
- Sku-123-dvv2
- Sku-123-dvv3
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/VersionProductsResponse'
examples:
getVersionProductsExample:
summary: Successful response
value:
info:
version_id: '76472'
version_status: ACTIVE
compared_with_version_id: '76326'
more_results_matching_the_request: true
offset: '1'
limit: '25'
products:
- sku: '56545'
name: Product A
type: PRODUCT
description: Description of product A
price:
EUR: '10'
USD: '12.5'
attributes:
- attr_x: value X
- attr_y: value Y
- sku: '56546'
name: Product B
type: PRODUCT
description: Description of product B
price:
EUR: '18'
USD: '21.5'
attributes:
- attr_x: value XX
- attr_y: value YY
- sku: 56545_b
name: Bundle X
type: BUNDLE
description: Description of bundle X
price:
EUR: '10'
attributes:
- attr_x: value XYZ
- attr_y: value YZ
bundle_items:
- '56545'
- '56546'
/api/v1/version/products_excel/{version_id}:
get:
tags:
- Product Catalog
summary: Extract Products to Excel
description: Retrieves all product-related information for a specific version in an Excel file format.
operationId: extractProductsExcel
parameters:
- name: version_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique identifier of the Version.
responses:
'200':
description: Success. Returns the Excel file as a byte array.
content:
application/vnd.ms-excel:
schema:
type: string
format: binary
/api/v1/version/{version_id}/products_catalog:
get:
tags:
- Product Catalog
summary: Get Product Catalog
description: Retrieves paginated information about products and bundles in the catalog, including attributes, assignments,
and pricing details.
operationId: getProductCatalog
parameters:
- name: version_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique identifier of the Version.
- name: sku
in: query
style: form
explode: true
schema:
type: array
items:
type: string
maxItems: 100
description: 'One or more product SKUs to filter the result. Can be used multiple times (e.g., `?sku=SKU001&sku=SKU002`).
If none of the provided SKUs match, the service will return an empty list.
In case you inform a list of SKUs, ‘limit’ and ‘offset’ parameters on request will be ignored if provided.'
- name: offset
in: query
schema:
type: integer
default: 0
description: The number of products to skip for pagination.
- name: limit
in: query
schema:
type: integer
default: 100
description: The maximum number of products to return.
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCatalogGetResponse'
examples:
getProductCatalogExample:
summary: Successful response
value:
products:
- sku: ABC-12345-S-BL
name: GRM Service
description: 'GRM Service
'
tags: []
primary_tag: null
merge_products: false
product_attributes:
Department:
type: NUMBER
value: '1022'
Model:
type: TEXT
value: 01-200-GRM-M
Manufacture Date:
type: DATE
value: May 31, 2024
product_assignments:
- assignment: RULE_BASED
playbook: Master_playbook_24
assignment_rules:
- ordinal: 0
name: Seasonal assignment
rule: '[General.partner_program] = "Direct Sales"'
note: null
product_factors:
- name: Duration
value: '12'
applicable: true
- name: Quantity
value: '1'
applicable: true
- name: Sits
value: '1'
applicable: false
proposal_attributes:
- name: custom_proposal_attribute
value: Direct
applicable: true
product_pricing:
advanced: true
pricing_rules:
- playbook: Master_playbook_24
ordinal: 0
currency: null
rule: ''
price: '0'
level: 0
note: null
price_format: BASIC
rounding_policy: null
dynamic_price: false
name: null
price_type: SOLID
apply_to: GENERATED_ITEMS
apply_to_templates: ''
apply_to_rules: ''
max_discount: '100'
default_discount: '0'
based_of_tags: ''
based_of_price: null
limit_type: AS_IS
limit_min_value: null
limit_max_value: null
disable_rounding: false
include_positive: false
volume_discount: {}
- playbook: Master_playbook_24
ordinal: 1
currency: null
rule: 'true'
price: '888'
level: 0
note: null
price_format: ADVANCED
rounding_policy: null
dynamic_price: false
name: null
price_type: SOLID
apply_to: GENERATED_ITEMS
apply_to_templates: ''
apply_to_rules: ''
max_discount: '100'
default_discount: '0'
based_of_tags: ''
based_of_price: null
limit_type: AS_IS
limit_min_value: null
limit_max_value: null
disable_rounding: false
include_positive: false
volume_discount: {}
product_conditional_names: []
bundles:
- sku: Products summary
name: Products summary
description: Products summary
tags:
- Products summary
primary_tag: Products summary
product_attributes:
Department:
type: NUMBER
value: '1111'
Model:
type: TEXT
value: '1117'
Manufacture Date:
type: DATE
value: '1111'
product_assignments:
- assignment: RULE_BASED
playbook: Master_playbook_24
assignment_rules:
- ordinal: 0
name: bundle3
rule: '[FixedSummary_bundles.Add_products_summary_bundle] = "Yes"'
note: null
product_factors:
- name: Duration
value: '1'
applicable: false
- name: Quantity
value: '1'
applicable: true
- name: Sits
value: '1'
applicable: false
proposal_attributes:
- name: custom_proposal_attribute
value: ''
applicable: true
product_pricing:
advanced: false
pricing_rules:
- playbook: Master_playbook_24
ordinal: 0
currency: null
rule: ''
price: '50'
level: 0
note: null
price_format: BASIC
rounding_policy: null
dynamic_price: false
name: null
price_type: FROM_ALL_QUOTE
apply_to: GENERATED_ITEMS
apply_to_templates: ''
apply_to_rules: ''
max_discount: '100'
default_discount: '0'
based_of_tags: ''
based_of_price: null
limit_type: AS_IS
limit_min_value: null
limit_max_value: null
disable_rounding: false
include_positive: false
volume_discount: {}
product_conditional_names: []
bundle_type: PRODUCT_SUMMARY
price_in_bundle_is_zero: false
sync_to_crm: true
sync_bundle_price: false
bundle_items:
- sku: Product2
ordinal: 1
how_to_add: AUTOMATIC
enable_modify_factors: false
product_factors:
- name: Duration
value: '1'
applicable: true
- name: Quantity
value: '2'
applicable: true
- name: Sits
value: '1'
applicable: true
- sku: Product3
ordinal: 2
how_to_add: MANUAL
enable_modify_factors: true
product_factors:
- name: Duration
value: '1'
applicable: true
- name: Quantity
value: '3'
applicable: true
- name: Sits
value: '0'
applicable: true
- sku: Product1
ordinal: 0
how_to_add: AUTOMATIC
enable_modify_factors: true
product_factors:
- name: Duration
value: '1'
applicable: true
- name: Quantity
value: '1'
applicable: true
- name: Sits
value: '0'
applicable: true
- sku: Product4
ordinal: 3
how_to_add: COMBINED
enable_modify_factors: false
product_factors:
- name: Duration
value: '1'
applicable: true
- name: Quantity
value: '4'
applicable: true
- name: Sits
value: '1'
applicable: true
info:
version_id: 7b34133847401b12
version_status: DRAFT
more_results_matching_the_request: false
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dealhub/refs/heads/main/openapi/dealhub-version-api-openapi.yml