DealHub Playbook API

openapi: 3.2.0
info:
  title: Version Playbook 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: 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.
paths:
  /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'
components:
  schemas:
    QuoteTemplateLineItem:
      type: object
      properties:
        sku:
          type: string
          description: Required. Product catalog identifier. Must exist in the DealHub catalog.
        item_name:
          type: string
          maxLength: 400
          description: Optional. Catalog product name.
        bundle_ref_sku:
          type: string
          description: Conditionally required. Bundle SKU reference. Required if part of a bundle; empty for the bundle product itself.
        bundle_ref_id:
          type: integer
          description: Conditionally required. Unique bundle instance ID. Required for items within a bundle and for the bundle itself.
        list_price:
          type: number
          format: double
          description: Required. List price. Positive or negative.
        net_price_per_unit:
          type: number
          format: double
          description: Optional. Net price per unit.
        net_price:
          type: number
          format: double
          description: 'Required. Total net price: net per unit multiplied by product factors.'
        msrp:
          type: number
          format: double
          description: Required. Line item MSRP. Positive or negative.
        msrp_discount:
          type: number
          format: double
          description: Required. Discount applied to MSRP. Positive or negative.
        sales_discount:
          type: number
          format: double
          description: Required. Sales discount. Positive or negative.
        total_discount:
          type: number
          format: double
          description: Required. Total discount. Positive or negative.
        product_factors:
          type: object
          additionalProperties: true
          description: Required. Product-specific factors (quantity, duration) as key-value pairs.
        attributes:
          type: object
          additionalProperties: true
          description: Optional. Line-item-specific proposal attributes as key-value pairs.
        partner_program_data:
          type: array
          items:
            $ref: '#/components/schemas/QuoteTemplatePartnerProgramData'
          description: Optional. Partner program-specific discounts.
    QuoteTemplateQuoteData:
      type: object
      properties:
        group_id:
          type: string
          maxLength: 50
          description: DealHub group ID. Required for each group in `quote_data`.
        questions:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
            description: Keys are `question_id`, values are answers. Multi-select answers use the `;` delimiter.
          description: Required. List of question answers. The template uses the default answer or the first answer for each question.
    PlaybookSyncSettings:
      type: object
      properties:
        enabled:
          type: string
          description: 'Sync configuration mode. Valid values: `ALWAYS`, `RULE_BASED`, `DISABLED`.'
        based_on:
          type:
          - string
          - 'null'
          description: Question ID used for the rule. Returns `null` when no rule applies.
    QuoteTemplatePartnerProgram:
      type: object
      properties:
        partner_level_name:
          type: string
          description: Partner level name.
        program_name:
          type: string
          description: Partner program name.
    PlaybookErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message.
        code:
          type: integer
          description: HTTP status code.
    PlaybookExportResponse:
      type: object
      properties:
        playbook_metadata:
          allOf:
          - $ref: '#/components/schemas/PlaybookMetadata'
          description: Playbook configuration metadata.
        playbook_data:
          type: array
          items:
            $ref: '#/components/schemas/PlaybookGroup'
          description: List of question groups in the Playbook.
    PlaybookGroup:
      type: object
      properties:
        group_id:
          type: string
          description: Unique group identifier.
        group_name:
          type: string
          description: Display name of the group.
        group_type:
          type: string
          enum:
          - QUESTIONS_GROUP
          - REPEATABLE_GROUP
          description: Group type.
        group_external_object:
          type:
          - string
          - 'null'
          description: External object reference.
        question_data:
          type: array
          items:
            $ref: '#/components/schemas/PlaybookQuestion'
          description: List of questions in the group.
    GenerateQuoteTemplateResponse:
      type: object
      description: Preformatted JSON template for the Generate Quote API, based on the Playbook structure.
      properties:
        external_opportunity_id:
          type: string
          maxLength: 50
          description: Required. CRM opportunity ID. Required in all requests.
        request_action:
          type: string
          enum:
          - draft
          - submit
          - publish
          - sign_externally
          description: Required. Action for the quote. Enum, lowercase.
        line_item_details:
          type: string
          enum:
          - basic
          - all
          default: basic
          description: Optional. Level of line item detail. `basic` includes SKU, bundle_ref, name, net price, list price, total discount, and product_factors.
        playbook:
          type: string
          maxLength: 50
          description: Optional. Unique name of the playbook (UTF-8). If missing, the system uses the first API-type playbook.
        quote_name:
          type: string
          maxLength: 250
          description: Optional. Quote or proposal name. The system default applies if missing; an error occurs if no default exists.
        dealroom_publish_name:
          type: string
          maxLength: 250
          description: Optional. DealRoom publish name. The system default applies if missing; an error occurs if no default exists.
        total_sales_discount:
          type: number
          format: double
          description: Optional. Total discount for all line items. Overrides individual line item discounts if provided.
        expiration_date:
          type: string
          description: Optional. Quote expiration date as a Unix timestamp in milliseconds (GMT). Must not be in the past; the system default applies if missing.
        document_type:
          type: string
          enum:
          - DealRoom
          - PDF
          - WORD
          - EXCEL
          description: Required. Type of document.
        timezone_offset:
          type: number
          minimum: -12
          maximum: 14
          default: 0
          description: Optional. Timezone offset from GMT.
        partner_program:
          type: array
          items:
            $ref: '#/components/schemas/QuoteTemplatePartnerProgram'
          description: Optional. Selected partner programs.
        quote_data:
          type: array
          items:
            $ref: '#/components/schemas/QuoteTemplateQuoteData'
          description: Required. List of question groups and answers.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/QuoteTemplateLineItem'
          description: Optional. List of line items.
        sign_externally_comment:
          type: string
          maxLength: 1000
          description: Conditionally required. Comment for external signing. Required if `request_action` = `sign_externally`.
    QuoteTemplatePartnerProgramData:
      type: object
      description: Partner program-specific discounts.
      properties:
        partner_program_name:
          type: string
          maxLength: 200
          description: Partner program name.
        partner_level_item_price:
          type: number
          format: double
          description: Partner level item price.
        partner_level_item_discount:
          type: number
          format: double
          description: Partner level item discount.
    PlaybookQuestion:
      type: object
      properties:
        question_id:
          type: string
          description: Unique question ID.
        question:
          type: string
          description: Question label/text.
        question_type:
          type: string
          description: 'Type of question. Valid values: `text`, `text_list`, `numeric`, `date`.'
        answers:
          type: string
          description: Possible answers, separated by a semicolon.
        default_answer:
          type:
          - string
          - 'null'
          description: Default answer used for API template generation.
    PlaybookMetadata:
      type: object
      properties:
        name:
          type: string
          description: Internal playbook name.
        display:
          type: string
          description: Playbook display name.
        document_type:
          type: array
          items:
            type: string
            enum:
            - PDF
            - WORD
            - EXCEL
            - DEALROOM
          description: List of allowed proposal document types.
        geo_factors_settings:
          type: boolean
          description: Enables geo factor logic.
        present_proposal_summary:
          type: boolean
          description: Shows the proposal summary.
        enable_partner_support:
          type: boolean
          description: Indicates whether partner support is enabled.
        sync_docs_settings:
          allOf:
          - $ref: '#/components/schemas/PlaybookSyncSettings'
          description: Sync docs configuration.
        sync_products_settings:
          allOf:
          - $ref: '#/components/schemas/PlaybookSyncSettings'
          description: Sync products configuration.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A secret token generated by a CPQ administrator.