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": Distribution Discount answer: '55' - system_id: 12345zWIWGV12349 system_name: 3yr group_id: SE_DISCOUNT group_name: SE Discount question_id: Special discount question: Advanced Options 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