Retrieve quotes and quote documents from DealHub, list quotes for a CRM opportunity, create renewal opportunities and read DealRoom signer status. The read side of the CPQ platform used to feed BI systems and downstream integrations.
openapi: 3.0.3
info:
title: Quote API
description: 'This API provides a set of services for managing and retrieving quote information from the DealHub platform.
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: Quote Management
description: Endpoints for retrieving and managing quotes, opportunities, and related documents.
paths:
/api/v2/quote/{quote_id}:
get:
tags:
- Quote Management
summary: Get a Specific Quote
description: 'Retrieves the details of a single existing quote by its DealHub Quote ID.
This endpoint allows you to fetch specific data points for any quote in DealHub. The level of detail in the response
is controlled by the **`feature`** query parameter.
- **Minimal Response**: If you don''t specify any `feature` parameters, the API returns a basic response containing
only the `dealhub_quote_id`, its current `status`, and the `quote_upgrade_required` flag.
- **Detailed Response**: To get more information, you must include one or more `feature` query parameters in your
request.
If a Draft quote was created using an older one, now-inactive version, the `quote_upgrade_required` flag will be `true`.
When this occurs, the API will not return any requested `feature` data for that quote.
> 📘 Date Formats
>
> All date values in the response are returned in `yyyy-mm-dd hh:mm:ss` format.'
operationId: getQuoteById
parameters:
- name: quote_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique identifier for the quote in DealHub.
- name: feature
in: query
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- info
- summary
- deal_room_info
- line_items
- answers
- approvals
- all
description: 'Specify which parts of the quote data to retrieve. This parameter can be used multiple times.
Valid options are:
* `info`
* `summary`
* `deal_room_info`
* `line_items`
* `answers`
* `approvals`
* `all`'
- name: external_identifier_flag
in: query
schema:
type: boolean
default: false
description: If true, the `quote_id` in the path refers to the `external_quote_id` from the CRM.
responses:
'200':
description: Success. Returns the detailed quote object.
content:
application/json:
schema:
$ref: '#/components/schemas/Quote'
examples:
fullQuoteDetails:
summary: Complete response
value:
dealhub_quote_id: 12345zWIwGV12344
status: ReadyToBeSent
quote_upgrade_required": false
info:
external_opportunity_id: '2077636'
external_quote_id: ''
external_customer_id: '101008'
customer_id: '6951040'
account_name: Example Ltd
contact_name": null
contact_email": ''
dealhub_opportunity_id: 12345zWIwGV12345
dealhub_quote_name: 3 year quote
dealhub_quote_number: Q_101
duplicate_from_quote: ''
primary_quote": false
created_by: antony@mydomain.com
creation_date: '2022-04-11 07:08:59'
submitted_by: antony@mydomain.com
submission_date: '2022-04-11 07:19:16'
expiration_date: '2022-05-11 09:04:02'
geo_code: EMEA
currency: USD
playbook: Playbook
version_id: 12345zWIWGV12346
summary:
currency: USD
total_list_price: 458154.42
total_net_price: 238042.66
total_discount: 48.04
sales_discount: 0
line_items":
- id: 12345zWIwGV12347
sku: '999451'
bundle_ref: ''
name: Gold Shield Pack
primary_tag: PS
msrp: 50000.04
msrp_discount: 55
list_price: 50.04
user_price: 22.02
net_per_unit: 22.02
partner_discounts: []
sales_discount: 55
total_discount: 55
net_price: 22500.02
product_factors:
duration: '1.0'
quantity: '1.0'
attributes:
ARR: '22.02'
Customer Discount: '49.07'
Item Status: Active
End Reseller Price": '-'
Inventory Category: DEFAULT
Product Line: Professional Services
answers:
- system_id: 12345zWIwGV12349
system_name: 3yr
group_id: SE_DISCOUNT
group_name: SE Discount
question_id: Distibrutor Discount
question": <font face="Arial" color=#36749D>Distribution Discount</font>
answer: '55'
- system_id: 12345zWIWGV12349
system_name: 3yr
group_id: SE_DISCOUNT
group_name: SE Discount
question_id: Special discount
question: <font face="Arial" color=#36749D>Advanced Options</font>
answer: '"No"'
- system_id: 12345zWIWGV12349
system_name: 3yr
group_id: Line
group_name: D-Line
question_id: Multimode
question": Multimode
answer: '0'
approvals: []
'400':
description: Bad Request. The quote is in draft status or the requested document type is not supported.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v2/quotes:
get:
tags:
- Quote Management
summary: Get a List of Quotes
description: "Retrieves a list of quotes, with options for filtering and pagination. \n\nUse the `external_opportunity_id`\
\ query parameter to retrieve only the quotes linked to a specific opportunity in your CRM.\n\nThe level of detail\
\ returned for each quote is controlled by the `feature` query parameter.\n\nUse the `offset` and `limit` parameters\
\ to page through large sets of quotes. The default `limit` is 50 quotes per request.\n\nIf no quotes match the specified\
\ criteria, the API will return a `200 OK` status with an empty `quotes` array.\n\n> \U0001F4D8 Date Formats\n>\n\
> All date values in the response are returned in `yyyy-mm-dd hh:mm:ss` format."
operationId: getQuotes
parameters:
- name: external_opportunity_id
in: query
schema:
type: string
maxLength: 50
description: Filter quotes associated with a specific CRM opportunity ID.
- name: feature
in: query
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- info
- summary
- deal_room_info
- line_items
- answers
- approvals
- all
description: 'Specify which parts of the quote data to retrieve for each quote in the list. This parameter can be
used multiple times.
Valid options are:
* `info`
* `summary`
* `deal_room_info`
* `line_items`
* `answers`
* `approvals`
* `all`'
- name: offset
in: query
schema:
type: integer
minimum: 0
maximum: 10000
description: The number of quotes to skip for pagination.
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 50
description: The maximum number of quotes to return.
responses:
'200':
description: Success. Returns a paginated list of quotes.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedQuotesResponse'
examples:
paginatedListOfQuotes:
summary: Quotes with minimal details
value:
info:
more_results_matching_the_request: true
offset: '1'
limit: '25'
quotes:
- dealhub_quote_id: 12345zWIwGV12344
status: ReadyToBeSent
quote_upgrade_required: false
- dealhub_quote_id: 12345zWIwGV12347
status: Draft
quote_upgrade_required": true
- dealhub_quote_id: 12345zWIwGV12349
status: Draft
quote_upgrade_required": false
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v1/opportunity:
post:
tags:
- Quote Management
summary: Create an Opportunity
description: Creates a new opportunity within DealHub, typically used for renewal automation.
operationId: createOpportunity
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOpportunityRequest'
examples:
createOpportunityExample:
summary: Create a new opportunity
value:
external_opportunity_id: vadim-test-01
external_opportunity_name": vadim-test-01-opp
opportunity_owner:
login: liotr
external_user_id: '11'
email: vadim@myDomain.io
name: Vadim T
position: Sales
phone: 03-12345678
mobile: 051-12345678
fax: 03-12345679
company: Acme Partner1
street: 12nd Broadway
city: New York
state: NY
country: USA
postal_code: '1234567'
user_manager_login: manager@domain.com
currency: USD
external_customer_id: br768
customer_name: Vadim Test1
responses:
'200':
description: Success. The opportunity was created.
'400':
description: Bad Request. The opportunity with the specified ID already exists or the payload is invalid.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v1/quote/{dealhub_quote_id}/document:
get:
tags:
- Quote Management
summary: Get Quote Document
description: 'Retrieves the output document (e.g., PDF, Word) for a submitted quote. Use this endpoint to archive contracts
or integrate quote documents into other systems.
By default, the endpoint returns the document in the format and template that the salesperson originally generated.
You can use the optional `document_type` query parameter to request the document in a different format (e.g., `PDF`,
`WORD`). However, this is only possible if the requested format has been enabled for the quote''s playbook in the
CPQ settings.
> 📘 Excel Files
>
> A quote document can only be retrieved in `EXCEL` format if the quote was explicitly configured to allow an Excel
file output.'
operationId: getQuoteDocument
parameters:
- name: dealhub_quote_id
in: path
required: true
schema:
type: string
maxLength: 16
description: The unique DealHub ID of the quote.
- name: document_type
in: query
schema:
type: string
enum:
- PDF
- WORD
- EXCEL
description: Specifies the desired document format.
responses:
'200':
description: Success. Returns the document file.
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Bad Request. Document retrieval for a draft quote is not supported or the document type is invalid.
'403':
description: Forbidden. Invalid or missing authentication token.
/api/v1/dealroom/{opportunity_id}:
get:
tags:
- Quote Management
summary: Get DealRoom Signers
description: Retrieves information about who has signed a contract within a DealRoom for a specific opportunity.
operationId: getDealRoomSigners
parameters:
- name: opportunity_id
in: path
required: true
schema:
type: string
description: The ID of the CRM opportunity.
responses:
'200':
description: Success. Returns the list of signers.
content:
application/json:
schema:
$ref: '#/components/schemas/DealRoomSignersResponse'
examples:
partiallySignedDealRoom:
summary: Partially Signed DealRoom
value:
dealroom_state: Partially signed
buyer_signers:
- company_name: BBB Inc.
signee_name: John Brown
signee_title: CEO
signature_date: '2024-02-06 16:41:29'
ordinal: 1
seller_signers: []
'400':
description: Bad Request. No DealRoom instance found for the given opportunity ID.
'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:
QuoteInfo:
type: object
properties:
external_opportunity_id:
type: string
description: External opportunity ID (CRM opportunity ID as provided during create quote call).
external_quote_id:
type: string
description: External quote ID (as provided during create quote call).
external_customer_id:
type: string
description: External customer ID (CRM customer account ID).
customer_id:
type: string
description: CPQ customer account ID.
account_name:
type: string
description: Account name (as provided during quote creation).
contact_name:
type: string
description: Primary customer contact full name.
contact_email:
type: string
format: email
description: Primary customer contact email.
dealhub_opportunity_id:
type: string
description: DealHub opportunity ID.
dealhub_quote_name:
type: string
description: DealHub quote name.
dealhub_quote_number:
type: string
description: Quote ID that is unique per account and presented to user in CPQ UI.
duplicate_from_quote:
type: string
description: Represents the quote ID (also referred as **Quote Num** in the CPQ UI) from which the current quote
was created using the duplication process. If the current quote was duplicated or cloned from another quote, this
field will contain the original quote's ID. If the quote was not created through duplication, this field will
be empty.
primary_quote:
type: boolean
description: Primary quote flag.
created_by:
type: string
format: email
description: Login of the user who created the quote.
creation_date:
type: string
format: date-time
description: GMT date&time of quote creation.
submitted_by:
type: string
format: email
description: Login of the user who submitted the quote (if specific quote is submitted).
submission_date:
type: string
format: date-time
description: GMT date&time of quote submission (if specific quote is submitted).
expiration_date:
type: string
format: date-time
description: Quote expiration date.
won_date:
type: string
format: date-time
description: The date the quote was signed.
geo_code:
type: string
description: Geographic code.
currency:
type: string
description: Quote currency.
playbook:
type: string
description: Playbook name.
quote_url:
type: string
format: uri
description: Quote URL.
version_id:
type: string
description: ID of the version in which the quote is managed.
QuoteSummary:
type: object
properties:
currency:
type: string
description: Quote currency (ISO-4217 format).
total_list_price:
type: number
format: float
description: The total list price of the quote.
total_net_price:
type: number
format: float
description: Total net price of the quote.
total_discount:
type: number
format: float
description: Total discount of the quote.
sales_discount:
type: number
format: float
description: Total discount provided by seller.
DealRoomInfo:
type: object
properties:
url:
type: string
format: uri
description: DealRoom URL.
LineItem:
type: object
properties:
id:
type: string
description: Unique identifier of the line item instance in this quote.
sku:
type: string
description: Product catalog unique identifier.
bundle_ref:
type: string
description: Reference of the line item to its bundle (Bundle SKU).
name:
type: string
description: Product catalog name.
primary_tag:
type: string
description: Product primary tag.
system_name:
type: string
description: System name, relevant in case of multi-system concept.
system_id:
type: string
description: System ID, relevant in case of multi-system concept.
system_ordinal:
type: integer
description: Defines the system's position/order within the quote.
group_name:
type: string
description: Name of the group that triggered creation of the line item.
ordinal:
type: integer
description: The position of the line item as displayed to the seller.
msrp:
type: number
format: float
description: Line item MSRP.
msrp_discount:
type: number
format: float
description: MSRP discount.
list_price:
type: number
format: float
description: Line item list price.
user_price:
type: number
format: float
description: End user price. Relevant for indirect sale (partners).
user_discount:
type: number
format: float
description: End user discount. Relevant for indirect sale (partners).
net_per_unit:
type: number
format: float
description: Unit net price.
net_price:
type: number
format: float
description: Total net price of the line item.
partner_discounts:
type: array
description: List of partner level discounts (indirect sale).
items:
type: object
properties:
name:
type: string
description: Partner program name.
discount:
type: number
format: float
description: Discount percentage.
price:
type: number
format: float
description: Price after partner discount.
sales_discount:
type: number
format: float
description: Sales discount.
total_discount:
type: number
format: float
description: Total discount.
product_factors:
type: object
description: List of all products factors (e.g. quantity, duration, etc) relevant for specific line item.
additionalProperties:
type: string
attributes:
type: object
description: List of line item attributes (aka proposal attributes).
additionalProperties:
type: string
PlaybookAnswer:
type: object
properties:
system_name:
type: string
description: Name of the system, relevant for multi-system concept.
system_id:
type: string
description: System ID, relevant for multi-system concept.
group_id:
type: string
description: Group ID.
group_name:
type: string
description: Group name.
question_id:
type: string
description: Question ID.
question:
type: string
description: Question text.
answer:
type: string
description: The answer.
Approval:
type: object
properties:
reviewer:
type: string
format: email
description: Login of the reviewer.
step:
type: integer
description: Approval workflow step.
reason:
type: string
description: List of approval reasons.
status:
type: string
enum:
- waiting
- rejected
- approved
description: Status of the specific step within approval flow.
impersonated_by:
type: string
format: email
description: Login of the person who approved/rejected quote on behalf of approver.
review_date:
type: string
format: date-time
description: Date of approval/rejection.
reviewer_comment:
type: string
description: Note added by reviewer.
Quote:
type: object
properties:
dealhub_quote_id:
type: string
status:
type: string
quote_upgrade_required:
type: boolean
info:
$ref: '#/components/schemas/QuoteInfo'
summary:
$ref: '#/components/schemas/QuoteSummary'
deal_room_info:
$ref: '#/components/schemas/DealRoomInfo'
line_items:
type: array
items:
$ref: '#/components/schemas/LineItem'
answers:
type: array
items:
$ref: '#/components/schemas/PlaybookAnswer'
approvals:
type: array
items:
$ref: '#/components/schemas/Approval'
PaginationInfo:
type: object
properties:
more_results_matching_the_request:
type: boolean
offset:
type: string
limit:
type: string
PaginatedQuotesResponse:
type: object
properties:
info:
$ref: '#/components/schemas/PaginationInfo'
quotes:
type: array
items:
$ref: '#/components/schemas/Quote'
OpportunityOwner:
type: object
description: Details of opportunity owner.
required:
- external_user_id
- email
- name
properties:
external_user_id:
type: string
maxLength: 200
description: CRM user ID (employee of the organization that integrates with DealHub).
login:
type: string
maxLength: 100
description: Login of the user.
email:
type: string
format: email
maxLength: 100
description: Primary email of the user.
name:
type: string
maxLength: 300
description: User full name.
position:
type: string
maxLength: 300
description: The role of the user in the organization (job title).
phone:
type: string
maxLength: 50
description: User phone number.
mobile:
type: string
maxLength: 100
description: User mobile phone number.
fax:
type: string
maxLength: 100
description: User fax number.
company:
type: string
maxLength: 100
description: User 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 user manager.
CreateOpportunityRequest:
type: object
required:
- external_opportunity_id
- external_opportunity_name
- opportunity_owner
- currency
- external_customer_id
- customer_name
properties:
external_opportunity_id:
type: string
maxLength: 50
description: CRM opportunity ID.
external_opportunity_name:
type: string
maxLength: 200
description: CRM opportunity name.
opportunity_owner:
$ref: '#/components/schemas/OpportunityOwner'
currency:
type: string
maxLength: 3
description: Opportunity currency (ISO code).
external_customer_id:
type: string
maxLength: 50
description: CRM customer ID (buyer account).
customer_name:
type: string
maxLength: 256
description: CRM customer name.
Signer:
type: object
properties:
company_name:
type: string
description: Company name of the signer.
signee_name:
type: string
description: Name of the signer.
signee_title:
type: string
description: Title of the signer.
signature_date:
type: string
format: date-time
description: Date when the user signed the contract via the DealRoom.
ordinal:
type: integer
description: The order of the signer in the list of signers.
DealRoomSignersResponse:
type: object
properties:
dealroom_state:
type: string
description: State of the DealRoom.
buyer_signers:
type: array
description: List of signers from the buyer side.
items:
$ref: '#/components/schemas/Signer'
seller_signers:
type: array
description: List of signers from the selling organization side.
items:
$ref: '#/components/schemas/Signer'
x-readme:
explorer-enabled: true
proxy-enabled: true